REST API 是 Web 应用开发中最常见的 API 风格. REST API 的风格要满足我们在上一篇文章中所提及的六个约束要求。这六个约束要求并没有严格规定 REST API 应该是什么样子,而是设计原则和指导。在不同的网络环境中,使用特定的通信协议,设计出来的 REST API 也不是完全相同的。
下面我们就研究一个在 Web 应用中,基于 HTTP 协议调用的 REST API.
HTTP 请求和响应
在线上购买自行车场景中,如果 API 的消费者想要获取一辆自行车的详细信息,该怎么办呢?API 的消费者必须向提供 API 的服务器发送一个请求:
GET /bikes/B007 HTTP/1.1
Accept: application/json, text/plain, */*
Host: lowtea.vip
很明显,这是一个 HTTP 请求。请求的内容做了简化,只保留了必要的内容。这一段请求的含义是:
-
GET
- 表示 HTTP 的一个方法,常用的方法还有 POST,PUT,DELETE 等。 -
/bikes/B007
- 表示路径,标识出资源在服务器上的地址或位置。 -
Accept
- 表示接受的响应数据的格式。 -
Host
- 表示提供 API 的服务器。
在这里,GET /bikes/B007
就是 REST API 的表示。
再来看看响应:
HTTP/1.1 200 OK
{
"bikeId": “B007”,
"name": "一骑绝尘”,
"price": “1999.00”,
"brand": “NilBrand”
}
服务器响应的第一部分是 HTTP 的状态码(200)和原因(OK)。状态码表示请求处理的结果,原因是对结果的进一步说明。从返回的原因 OK,可以猜到,请求处理成功了。服务器响应的第二部分是响应体(response body),包含了请求路径所对应的资源内容,也就是我们的自行车信息。响应体是一个 JSON 格式的数据,包含了自行车的信息:编号,名称,价格和品牌。
REST API
接下来,我们把目标和 REST API 做一个映射,如下图:
REST API 的消费者使用 HTTP 方法操作由路径标识的资源。/bikes/{bikeId}
既表示自行车目录中一辆自行车,也标识了一个服务器中的资源。HTTP 的 GET 方法表示检索动作,相对应的就是获取资源的操作。
小结
调用 REST API 与发送 HTTP 请求完全相同。最关键的就是方法/操作和路径/资源的映射。