RESTful API 设计问答之二: 使用控制器 (controller) 还是使用 PUT 来修改资源?

有人说过 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 不太好用。它的优点是，这样做可以让日志分析简单些，因为请求包里已经包含了整个对象信息。我们不需要再去数据库里找相关的信息了。