# 3.5 RESTful Web API ## 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](url.html)的查询（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](request.html#request-line) ``` /compute/sum ``` 所代表的服务器上的运算能力。 ### RESTful RESTful就是具有REST风格的意思。REST是**Representational State Transfer**的简称，一个难以顾名思义的名词。 其实它也不是那么难以理解。 首先我们要搞清楚什么是*representation*。Representation就是“代表”的意思，比如在奥运会上运动员代表着国家，在人大会议上人大委员代表着人民，等等。在Web的世界里，我们用URI代表一个资源。比如，在前面的Web API的例子里， ``` /compute/sum ``` 就代表着www.example.com上的一种计算资源。资源可以是任何事物[1](#fn_1)，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》](http://shop.oreilly.com/product/0636920028468.do) 这本书全面介绍了RESTful Web API的概念和设计要点，循序渐进。 - [《RESTful Web Services Cookbook》](http://shop.oreilly.com/product/9780596801694.do) 如果你正在寻找某个关于RESTful设计的具体问题，例如“何时应该使用GET/POST/...方法”，“如何识别资源”等，这本书可以告诉你答案。 以上两本书均由OReilly出版，也有中译版。 > 1. 我们早在[HTTP - 客户端请求](request.html)就提到过这一点，在[Web服务器 - 方法与资源](http_method_and_resource.html)一节也重申过，如果忘记了请重温一下——资源是一个重要的抽象概念。[↩](#reffn_1 "Jump back to footnote [1] in the text.")