3.5 RESTful Web API

RESTful Web API就是按照REST方式设计的Web API。本章首先介绍Web API是什么，然后解释RESTful的含义，最后给出进一步学习的建议。

Web API

API即应用程序编程接口，比如*nix操作系统提供的C语言接口的API可以完成创建进程、读取系统时间等各种操作。Web API也是同样，只不过不是直接调用某个代码库里的函数，而是通过HTTP来调用。一个简单的Web API调用的例子如下：

GET /compute/sum?x=1&y=2 HTTP/1.1
Host: www.example.com

假设www.example.com提供一个加法运算Web API

GET /compute/sum

它接受两个参数x和y，通过URL的查询（query）部分传递。上面的代码通过HTTP调用了它，并传给它两个参数

x=1&y=2

www.example.com的一个可能的回应是：

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 1

3

这个简单的例子已经说明了Web API的本质：客户端请求服务器对某种资源进行某种操作，通过HTTP协议发送请求以及请求的参数，并得到结果。在这个例子中，资源就是由Request URI

/compute/sum

所代表的服务器上的运算能力。

RESTful

RESTful就是具有REST风格的意思。REST是Representational State Transfer的简称，一个难以顾名思义的名词。

其实它也不是那么难以理解。

首先我们要搞清楚什么是representation。Representation就是“代表”的意思，比如在奥运会上运动员代表着国家，在人大会议上人大委员代表着人民，等等。在Web的世界里，我们用URI代表一个资源。比如，在前面的Web API的例子里，

/compute/sum

就代表着www.example.com上的一种计算资源。资源可以是任何事物¹，URI就是它的代表。

明白了representation是“代表”，就不难明白Representational State是指这种代表的状态，实际上就是服务器上的资源的状态。比如说，我们用/users代表网站的注册用户，那么这个资源的状态可以是数据库里注册用户表下的数据的状态；当我们新增／删除／更改用户时，资源的状态就发生了改变——这就是Representational State Transfer。

RESTful Web API

在具体设计上，RESTful Web API强调利用HTTP方法（Request Method）的语义来定义资源状态转换的各种操作。一个典型的例子如下：

GET /users

获取用户列表。

POST /users

新增用户。

GET /users/:id

获取以:id标识的用户。

PATCH /users/:id

更新以:id标识的用户。

DELETE /users/:id

删除以:id标识的用户。

以上GET、POST、PATCH和DELETE都是HTTP方法，其中PATCH有时也以PUT方法代替（但它们是有差别的）。有些贯彻了REST的Web开发框架，如Ruby on Rails，会自动为你生成类似上面的代码。

进一步了解

以上就是关于REST的一点“Hello, World!”级别的介绍。REST内涵深刻，实现方式上也有很多可以说的地方，限于篇幅，这里仅介绍了一些皮毛。对于有兴趣的读者，我推荐：

《RESTful Web APIs》这本书全面介绍了RESTful Web API的概念和设计要点，循序渐进。
《RESTful Web Services Cookbook》如果你正在寻找某个关于RESTful设计的具体问题，例如“何时应该使用GET/POST/...方法”，“如何识别资源”等，这本书可以告诉你答案。

以上两本书均由OReilly出版，也有中译版。

¹. 我们早在HTTP - 客户端请求就提到过这一点，在Web服务器 - 方法与资源一节也重申过，如果忘记了请重温一下——资源是一个重要的抽象概念。 ↩

3.5 RESTful Web API