有人说过 API 设计师就是程序员的用户体验工程师。优秀的 API 设计应该在用户使用起来方便的同时程序员实现起来也很简单。
下面的系列文章是我的 API 设计工作中总结了一些技巧。大家看看是不是有用?您可以留言告诉我您的如何让 API 易用的想法。
使用控制器 (controller) 还是使用 PUT 来修改资源?
问题
在 RESTful API 设计中, 一般建议使用 PUT 来修改资源,但是我们也会看到 API 用控制器 (controller) 带着这个 POST 方法来修改资源。哪种方法更好呢?
在使用 PUT 的时候,我们一般会把整个对象都传回服务器,但是在大多数情况下,我们只是想修改对象的某一个属性。这是一个很小的改动。对于程序员来说,把整个对象传回服务器会让他们很困惑。你想修改的到底是什么啊?
答案
如果你只是想修改某个属性,那就用控制器来把参数最小化吧。
示例
你可以看到下面的示例中同样是修改一个叫 CPV 的对象,使用 PUT 和使用控制器有何异同。
PUT
下面的图片显示了使用 API 把 CPV 的状态从 Redeemed 改为 Voided。请求包是整个 CPVInfo 对象,但是需要的属性只有 CPV ID, CPV status 和 TransactionInfo 属性。API 设计者需要告诉程序员在这个API 里只需要哪些属性,程序员才能正确调用这个 API。这就让这个 API 不太好用。它的优点是,这样做可以让日志分析简单些,因为请求包里已经包含了整个对象信息。我们不需要再去数据库里找相关的信息了。