RESTful API

极客时间《如何落地业务建模》学习笔记 11

10 | 将模型实现为 RESTful API（上）

RPC 风格（Remote Procedure Call Style）的 API 设计，从人机交互入手，从行为角度构建 API，面向过程编程，似乎更符合人的一般想法。

交互将隐藏在领域模型中的业务维度展开，让业务方理解不同的业务流程如何作用域领域模型，交互是业务维度在领域模型上的补充。

因为写过一点 Ruby 的代码，所以对于 Restful API 并不陌生，“使用 URI 表示所需修改的对象，然后再说明希望对象发生什么样的改变”，面向对象风格，逻辑集中于对象，对象访问可以触发相应的逻辑。

模型是从数据变化的角度描述业务，具体的业务流程反而是被隐藏的。

URI 的模板长一点没有关系，也可以从可读性上考虑。当然如果长度超出了 http 协议的最大长度，那么的确是需要重新审视一下了。

简单查了一下，IE 11 的最大字符长度为 2,083 characters，其他的浏览器比如 Chrome、Firefox、Safari 似乎都要多一些，但是一般来说，保持在 2000 chars 之内是适用性比较好的。

如果 URL 超长的话，一般会返回 414 错误（Request-URI Too Long）。

对于“读者将自己的专栏赠送给朋友”的 URI：

PUT /users/{user_id}/subscriptions/{subscription_id} 

有一点奇怪，但是好像也没有更好的选择。

RFC-2616 clearly mention that PUT method requests for the enclosed entity be stored under the supplied Request-URI.

If the Request-URI refers to an already existing resource – an update operation will happen, otherwise create operation should happen if Request-URI is a valid resource URI (assuming client is allowed to determine resource identifier).

PUT method is idempotent.

Generally, in practice, always use PUT for UPDATE operations.

Always use POST for CREATE operations.

GET   /device-management/devices : Get all devicesPOST   /device-management/devices : Create a new device
GET   /device-management/devices/{id} : Get the device information identified by "id"PUT   /device-management/devices/{id} : Update the device information identified by "id"DELETE  /device-management/devices/{id} : Delete device by "id"

对于思考题，简单的说，可以使用相同的 API 对应不同的客户端（不同的数据格式），检查 request header 里面 User-Agent 或者 Referer，可以区分不同的不同的客户端和版本。可能还有 device-type 可以利用。

比如使用 xyz.com 和 m.xyz.com 来区分桌面和移动端，然后使用 domain.com/m/v1/api 来区分不同的客户端和数据格式（Rubyist 看着感觉和亲切）。