本文主要介绍 Restful 风格，如何设计 HTTP Restful API，以及在设计过程中的一点经验之谈。文章有点枯燥，敬请谅解。最后建议在设计 HTTP API 时，遵循 Restful API 风格。

理解 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 的核心特征，本文从实践角度出发，围绕 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

此外，在设计 uri 时，还应该注意如下要点：

• 尽量用小写：比如用 john，最好不要用 John。
• 用中杠 -，不用下杠 _

HTTP Method

HTTP 协议定义了 8 个 Method，在 Restful API 设计中，我们常用 POST，DELETE，PUT，GET 四方法来操作资源。其中 POST 表示创建资源，DELETE 表示删除某个资源，PUT 表示更新某个资源，GET 表示查询资源。例如，当我们要创建用户 andy 时，其 API 如下：

POST /uesrs Body: {"user": "andy", ...}

在设计 Restful API 时，应该遵循 HTTP 关于 “安全性” 和 “幂等性” 的要求。