Restful API接口设计规范

前言

RESTful API 设计规范是确保接口一致性、可维护性和易用性的关键。以下是一份全面且结构化的指南

一、什么是RESTful架构

RESTful API

• REST 是 Representational State Transfer的缩写，如果一个架构符合REST原则，就称它为RESTfuI架构
• RESTfuI架构可以充分的利用HTTP协议的各种功能，是HTTP 协议的最佳实践
• RESTfuIAPI是一种软件架构风格、设计风格，可以让软件更加清晰，更简洁，更有层次，可维护性更好

二、API请求设计（请求=动词+宾语）

1. HTTP 动词

动词 使用五种HTTP 方法，对应 CRUD操作。

GET： 读取（Read）
POST： 新建（Create）
PUT： 更新（Update）
PATCH： 更新（Update），通常是部分更新
DELETE：删除（Delete）

2. URL（宾语）必须是名词

宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。并且为了统一起见，建议都使用复数。比如，/articles这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。

/getAllCars
/createNewCar
/deleteAllRedCars

3. 过滤信息（Filtering）

过滤信息（Filtering）如果记录数量很多，API应该提供参数，过滤返回结果。?limit=10指定返回记录的数量？offset=10指定返回记录的开始位置。下面是一些常见的参数。

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

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

4. API请求设计

三、API响应设计

1. 使用HTTP的状态码

• 客户端的每一次请求，服务器都必须给出回应。回应包括HTTP状态码和数据两部分。
• 五大类状态码，总共100多种，覆盖了绝大部分可能遇到的情况。每一种状态码都有约定的解释，客户端只需查看状态码，就可以判断出发生了什么情况。HTTP状态码就是一个三位数，分成五个类别。

1xx：相关信息：表示请求已接收，继续处理。
2xx：操作成功：表示请求已成功被接收、理解、并被接受。
3xx：重定向：表示需要进一步操作以完成请求。
4xx：客户端错误：表示请求包含语法错误或无法完成。
5xx：服务器错误：表示服务器在处理请求时发生了错误。

API不需要1xx状态码。

2. 状态码

四、服务器回应数据

1. 不要返回纯本文

API 返回的数据格式，不应该是纯文本，而应该是一个 JSON对象，因为这样才能返回标准的结构化数据。所以，服务器回应的HTTP头的Content-Type属性要设为application/json。

客户端请求时，也要明确告诉服务器，可以接受JSON 格式，即请求的HTTP 头的ACCEPT属性也要设成application/json。

2. 不要包装数据

response的 body直接就是数据，不要做多余的包装。错误实例：

{"success":true, "data":{"id":1, "name":"周伯通"} }

针对不同操作，服务器向用户返回的结果应该符合以下规范。

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

3. 发生错误时，不要返回 200 状态码

有一种不恰当的做法是，即使发生错误，也返回200状态码，把错误信息放在数据体里面，就像下面这样。

{"status": "failure", "data": { "error": "Expected at least two items in list."} }

正确的做法是，状态码反映发生的错误，具体的错误信息放在数据体里面返回。下面是一个例子。

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "Invalid payoad.",
  "detail": {
    "surname": "This field is required."
  }
}

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可。(error: "Invalid API key"}

4. 认证RESTfuIAPI应该是无状态，每个请求应该带有一些认证凭证。推荐使用JWT认证，并且使用 SSL
5. Hypermedia即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么