Restful API 的设计

引子

Restful API 是如今比较常见的HTTP API设计方案了。不论是不是真的理解，不少项目组都开始运用restful思想设计API。前几天部门领导莅临指导，更是反复强调要 restful。姑且认为他也是通过深刻研究的吧。

优势和缺点

restful 是一种简单的设计方案。它认为网站，或者说后台服务是对资源的管理，包括建立，更新，获取和删除。实际设计的时候，须要对资源进行合理的抽象。

restful 指导原则比较简单，一切皆是资源，api 就是对资源的管理。那么问题来了，如何有效的抽象这些资源？ 好比， search 是很是常见的api，如何将它 restful 化呢？

基本原则

restful 认为一切皆是资源， API 应该是对资源的状态的转化。

url 路径中只应该包含资源标识符

好比，建立订单，非 restful API 多是这样的:

/createPO

这个业务中，PO是一种资源，restful 风格的 API 应该应该是

/PO

那么，如何标志这个API 是建立 PO 呢？

利用 http method 定义资源状态转化

上面的例子，可使用 POST 方法定义建立 PO。

POST /PO

restful 主张用http method来标志资源状态的转化，有下面四种：

• POST 建立

• PUT 更新

• GET 获取

• DELETE 删除

因此，对于PO,它的建立，更新，获取，删除，API以下

POST /PO
PUT /PO/:id
GET /PO/:id
DELETE /PO/:id

实践和思考

理论上来说，restful 是让 API 的设计变得简单了。抽象资源+状态转化。实际中要注意的是对资源的抽象应该在较高的层次，即实际的业务层次。我见过不少的程序员都习惯从数据库的角度来抽象资源，好比，一个表就对应一个资源。这是没有意义的，这样的API只是变相的对数据表的抽象，而非对资源的转化。由于不少表的数据原本是不该该被 API 操做的，并且，业务实体也不会映射到单一的数据表。说到底，API的用户，不论是第三方，仍是前台，它们关心的并非数据表的细节，而是业务实体。

因此，实际上的 POST API，也许并不只是建立一行数据，也许它也同时更新了某些数据，删除了某些数据，这些均可以依具体业务而定。建立资源并不等于在某个具体的表中插入数据，而是在高层次的业务实体上的建立。

上面的例子，其实实际业务通常不会这么简单，好比PO都会从属于某一个用户，因此API的结构会是下面这样,以 PUT 为例

PUT /user/:userid/PO/:poid

这里就引伸出一个值得讨论的话题，如何设计从属关系？从业务实体上设计从属关系可能会遇到一些困难，好比，某些状况下，父资源的建立可能会依赖子资源的建立。个人建议是，若是开销不大的话，能够从新设计一下业务。好比，PO必须从属于一个user，那么业务上就规定必须先注册（建立user）或者登录，才能下订单（建立PO）。

遇到困难的时候

有些时候会遇到一些设计上的困难，多是因为对 restful 的认识不深，或者业务实在太奇葩。若是不牵涉什么商业机密的话，能够向社区或者论坛求助。

当项目进度很是紧张的时候，这个时候仍是要以实现功能为先，避免被指责。:)

总结

技术的变革通常都是为了提升生产力的，restful的初衷也是。它提倡简单（理论上讲只要业务实体抽象的好就够了），纯粹（每一个资源就四种操做）的 API 设计思想，须要使用者坚持信仰（坚持基本原则），适度灵活。