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服务器 - 方法与资源一节也重申过,如果忘记了请重温一下——资源是一个重要的抽象概念。

results matching ""

    No results matching ""