RESTful API 规范

约束

客户-服务器(Client-Server),提供服务的服务器和使用服务的客户需要被隔离对待。

无状态(Stateless),来自客户的每一个请求必须包含服务器处理该请求所需的所有信息。换句话说,服务器端不能存储来自某个客户的某个请求中的信息,并在该客户的其他请求中使用。

可缓存(Cachable),服务器必须让客户知道请求是否可以被缓存。

分层系统(Layered System),服务器和客户之间的通信必须被这样标准化:允许服务器和客户之间的中间层(Ross:代理,网关等)可以代替服务器对客户的请求进行回应,而且这些对客户来说不需要特别支持。

统一接口(Uniform Interface),客户和服务器之间通信的方法必须是统一化的。

  • 资源标识符。每个资源都有各自的标识符。客户端在请求时需要指定该标识符。在 REST 服务中,该标识符通常是 URI。客户端所获取的是资源的表达(representation),通常使用 XML 或 JSON 格式。

  • 通过资源的表达来操纵资源。客户端根据所得到的资源的表达中包含的信息来了解如何操纵资源,比如对资源进行修改或删除。

  • 自描述的消息。每条消息都包含足够的信息来描述如何处理该消息。

  • 超媒体作为应用状态的引擎(HATEOAS)。客户端通过服务器提供的超媒体内容中动态提供的动作来进行状态转换。

支持按需代码(Code-On-Demand,可选),服务器可以提供一些代码或者脚本(Javascrpt,flash,etc)并在客户的运行环境中执行。这条准则是这些准则中唯一不必必须满足的一条。(比如客户可以在客户端下载脚本生成密码访问服务器。)

协议

API与用户的通信协议,总是使用HTTPs协议,确保交互数据的传输安全。

域名

应该尽量将API部署在专用域名之下。

  • https://api.example.com

如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。

  • https://example.org/api/

API版本控制

路径又称”终点”(endpoint),表示API的具体网址。
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的”集合”(collection),所以API中的名词也应该使用复数。

举例来说,有一个API提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样。

  • https://api.example.com/v1/products
  • https://api.example.com/v1/users
  • https://api.example.com/v1/employees

HTTP请求方式

对于资源的具体操作类型,由HTTP动词表示。
常用的HTTP动词有下面四个(括号里是对应的SQL命令)。

  • GET(SELECT):从服务器取出资源(一项或多项)。
  • POST(CREATE):在服务器新建一个资源。
  • PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
  • DELETE(DELETE):从服务器删除资源。

GET /product:列出所有商品。

POST /product:新建一个商品。

GET /product/ID:获取某个指定商品的信息。

PUT /product/ID:更新某个指定商品的信息。

DELETE /product/ID:删除某个商品。

GET /product/ID/purchase:列出某个指定商品的所有投资者。

GET /product/ID/purchase/ID:获取某个指定商品的指定投资者信息。

HTTP头部&HTTP状态码

针对不同的需求和不同的响应,Request应该采用相应的HTTP头部,Response应采用相应的HTTP状态码,方便服务端和用户端作出不同的响应。

  • Authorization 认证报头
  • Cache-Control 缓存报头
  • Content-Type 消息体类型报头

  • 200 OK

  • 400 Bad Request
  • 500 Internal Server Error

发表评论

您的电子邮箱地址不会被公开。 必填项已用*标注

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据