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上的一种计算资源。资源可以是任何事物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》 这本书全面介绍了RESTful Web API的概念和设计要点,循序渐进。
- 《RESTful Web Services Cookbook》 如果你正在寻找某个关于RESTful设计的具体问题,例如“何时应该使用GET/POST/...方法”,“如何识别资源”等,这本书可以告诉你答案。
以上两本书均由OReilly出版,也有中译版。
1. 我们早在HTTP - 客户端请求就提到过这一点,在Web服务器 - 方法与资源一节也重申过,如果忘记了请重温一下——资源是一个重要的抽象概念。 ↩