原文出处： koala bear

本文主要先容 Restful 气势气魄，如何设计 HTTP Restful API，以及在设计进程中的一点履历之谈。文章有点枯燥，敬请体谅。最后发起在设计 HTTP API 时，遵循 Restful API 气势气魄。

restful-style">领略 Restful Style

在 web 飞速成长的情况下，Roy Fielding 于 2000 年在博士论文 Architectural Styles and the Design of Network-based Software Architectures 提出 REpresentational State Transfer (REST) 观念，它建议一种新的 web 架构气势气魄，具有面向资源、松耦合、无状态、易扩展等特点，如今被遍及的应用。

那么什么是 REST 气势气魄呢，论文的第五章节 Representational State Transfer (REST) 做了具体说明，个中 uniform interface 是 REST 架构的最主要特征。

The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components…….

In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.

留意前两个约束：identification of resources 和 manipulation of resources through representations，它们表白 uniform interface(即 RESTful API) 的主体是 resource，即 REST 是面向 resource 的。那么什么是 resource 呢？任何可以或许被定名的事物都可称为 resource，好比某个文本、图像，甚至某种处事。在 web 中，我们回收 URI 来指代某个 resource。顾名思义，representation 就是资源的表示形式，好比图像资源的表示形式可为 JPEG image，文本资源的表示可为 text。

那么第三个约束 self-descriptive messages 暗示什么呢？论文是这样表明的，即回收 standard methods(如 HTTP Method) 和 media types(如 HTTP Content type) 来暗示操纵范例，举例来说，我们可以用 GET 要领暗示查询某个资源，用 DELETE 要领暗示删除某个资源。

第四个约束 hypermedia as the engine of application state 暗示 application 的状态由 request 抉择，即客户端通过发送 request 来改变 application 的状态。以 HTTP POST 为例，客户端可以新建一个 resource，因而改变了 application 的状态。

总结而言，uniform interface 的约束条件界说了 web application API 的气势气魄，即 RESTful API，这种 API 是面向 resource 的，操作(HTTP)尺度要领来描写操纵，客户端通过 representation 来操纵 resource，从而转化 resource 的状态。

推荐阅读

Architectural Styles and the Design of Network-based Software Architectures

restful-api">如何设计 Restful API

上节简朴的先容了 Restful 的焦点特征，本文从实践角度出发，环绕 URI，HTTP Method，Response Code，序列化和安详等，并团结一个详细的案例，谈谈 Http Restful API 设计的履历。

好比某个账号系统（http://example.com），凡是需要增删改查用户，我们就以增删改查用户(user)为例，具体的先容Restful API 的设计。

URI 设计

作为 Restful 的焦点特性，uniform interface 是面向资源的，我们用 URI 来指代某个资源。好比，我们用如下 URI 代表账号系统用户 john：

http://example.com/users/john
为了轻便，后续例子大概会省略域名，用 /users/john 表达沟通寄义。

查询用户 john 的请求如下。

GET /users/john

更新用户 john 的请求如下。

PUT /users/john

删除用户 john 的请求如下。

DELETE /users/john

从上可以看出，岂论是查询照旧删除用户 john，我们都用沟通的 URI 来表指代这个用户(资源)，回收差异的 Http Method 来暗示差异的操纵范例。既然 /users/john 指代的是用户 john，昆山软件开发，顾名思义，/users 指代的是所有的用户，所以可以用如下请求查询所有的用户信息。

GET /users

因为 URI 代表的是某个资源，而资源自己是个名词，所以在设计 URI 时，也应该用名词，切记不要利用动词等词语。好比，如下 URI 是面向行动的，不满意 Restful 气势气魄约束。

/users/getuser

帐户系统在差异阶段大概会有差异的版本，好比 v1，v2，我们凡是把版本号放在前面，好比：

/v1/users/john /v2/users/john

假如需要查询某些切合要求的资源，可在 URI 的 paras 模块配置查询参数，如查询所有性别为女的用户

GET /users?gender=female

假如返回功效过多，可以加上分页成果，如查询自 john 起的 10 位用户。

GET /users?limit=10&marker=john