Restful API规范解析

一、背景与基础概念

Web 应用程序最重要的 REST 原则是，客户端和服务器之间的交互在请求之间是无状态的。从客户端到服务器的每个请求都必须包含理解请求所必需的信息。

• 资源（resource）：网络上的一个实体或者说是一个具体信息，可以是一段文本、一张图片、一首歌曲、一种服务。
• 统一资源定位符（URI，Universal Resource Identifier）：一个资源的识别符或者说是一个地址，通过URI你可以定位到特定的资源。要获取这个资源，需要访问它的URI，因此，URI就成了每一个资源的地址或独一无二的识别符。
• 状态转换（State Transfer）: 所有资源都共享统一的接口，以便在客户端和服务器之间传输状态。客户端与服务器互动的过程，通常涉及到服务器端数据和状态的变化过程，比如文件被修改，访问数量增加等。使用的是标准的 HTTP 方法，Http标准中定义的最主要四个动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：
    - GET： 用来获取资源
    - POST： 用来新建资源
    - PUT： 用来更新资源
    - DELETE： 用来删除资源
• Hypermedia 是应用程序状态的引擎，资源表示通过超链接互联。

二、RESTful API应遵循的原则

1、协议(Protocol)
  API与用户的通信协议，尽量使用HTTPs协议。HTTPs协议的所有信息都是加密传播，第三方无法窃听，具有校验机制，一旦被篡改，通信双方会立刻发现，配备身份证书，防止身份被冒充。

2、域名(ROOT URL)
  应该尽量将API部署在专用域名之下。
  https://api.example.com
  如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
  https://example.org/api/

3、版本(Versioning)
应该将API的版本号放入URL。

4、路径(EndPoints)
路径表示API的具体网址URL。在RESTful架构中，每个URL代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与代表的对象名称对应。一般来说，某一同种记录的”集合”（collection），所以API中的名词也应该使用复数。

5、HTTP动词(HTTP Verbs)
  对于资源的具体操作类型，由HTTP动词表示。常用的HTTP动词有下面五个：

• GET（SELECT）：从服务器取出资源（一项或多项）

• POST（CREATE）：在服务器新建一个资源。

• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

• DELETE（DELETE）：从服务器删除资源。
    还有两个不常用的HTTP动词。

• HEAD：获取资源的元数据。

• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
  注：Get方法和查询参数不应该涉及状态改变。使用PUT, POST 和DELETE方法而不是 GET 方法来改变状态。

6、过滤信息（Filtering）
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。为集合提供过滤、排序、选择和分页等功能。
下面是一些常见的参数。

• ?limit=10：指定返回记录的数量
• ?offset=10：指定返回记录的开始位置。
• ?pageNumber=2&perSize=100：指定第几页，以及每页的记录数。
• ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
• ?animal_type_id=1：指定筛选条件

7、状态码（Status Codes）
服务器向用户返回的状态码和提示信息.

8、错误处理（Error handling）
如果状态码是4xx，就应该向用户返回出错信息。尽量使用详细的错误包装信息：

{
  "errors": [
   {
    "userMessage": "Sorry, the requested resource does not exist",
    "internalMessage": "No car found in the database",
    "code": 4xx,
    "more info": "http://dev.example.com/api/v1/errors/12345"
   }
  ]
}

9、返回结果（Response）
服务器返回的数据格式，应该尽量使用JSON，避免使用XML。针对不同操作，服务器向用户返回的结果应该符合以下规范。

• GET /collection：返回资源对象的列表（数组）
• GET /collection/resource：返回单个资源对象
• POST /collection：返回新生成的资源对象
• PUT /collection/resource：返回完整的资源对象
• PATCH /collection/resource：返回完整的资源对象
• DELETE /collection/resource：返回一个空文档

10、使用HATEOAS的Hypermedia API
RESTful API最好使用Hypermedia as the Engine of Application State（超媒体作为应用状态的引擎），即返回结果中提供链接，连向其他API方法，超文本链接可以建立更好的文本浏览，使得用户不查文档，也知道下一步应该做什么。

11、认证（Authentication）
API的身份认证尽量使用OAuth 2.0框架。

三、Swagger API标准

API的文档管理和信息描述，将使用Swagger进行。
  Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。

Swagger文件的构成以及规范信息，在Swagger官方的规范指导《Swagger RESTful API文档规范》中有详细描述，请参看。
http://swagger.io/specification/