RestApi 规范

1. 协议

API 和用户的交流协议，必须使用HTTPs。




2. 范围

API 应当部署在专用范围名称下。




3. 版本

URL地址里面应当包括API 版本号。


正确示例

v1, v2, v3


错误示例

v-1, 1.2




4. 端点

端点是API的特殊URL，在Restful架构范围内，每个URL代表一个资源，因此URL里面没有动词，只有名词，并且常常对应的是数据库表格名称。总体来说，数据库的表格是相同记录的集合，因此API里面的名词也应该使用复数。
URL的内容需要易懂并且易于创造。所有URL的内容必须是小写。当API 提供一个业务层面资源服务时，不应该在路径里出现此类应用组织的描述（不稳定并且和资源没有必要的业务联系的应用组织）。


正确示例


https://api.example.com/v1/departments?sort=name
https://api.example.com/v1/products/1234
https://api.example.com/v1/employees/



错误示例



https://api.example.com/v1/product/1234               (noun does not use plural)

https://api.example.com/v1/ProductGroup/Update        (case used)

https://api.example.com/v1/prdocuts/query             (verbs used)

https://api.example.com/v1/pcsdproducts/1234          (IT organization information appears)

https://api.example.com/v1/ews/odata/users('jdoe@example.com')/folders('AAMkADdiYzI1MjUzLTk4MjQtNDQ1Yy05YjJkLWNlMzMzYmIzNTY0MwAuAAAAAACzMsPHYH6HQoSwfdpDx-2bAQCXhUk6PC1dS7AERFluCgBfAAABo58UAAA= ') (contains abbreviations and technical terms contents can not be understood)





5. HTTP 动词

HTTP 动词可以代表一个资源的特殊操作类型。通用的HTTP动词有以下5种（对应的圆括号SQL命令）



GET (选择)：从服务器中移除资源。

POST (创建):在服务器中创建一个新的资源。

PUT (更新)：更新服务器中的资源（客户端提供更新的属性）。

PATCH (更新)：更新服务器中的资源（客户端提供更新的属性）。

DELETE (删除):从服务器中删除资源，有两个以上的非普遍性的HTTP动词。

HEAD 得到资源的元数据。

OPTIONS 得到关于客户可以更改哪些资源属性的信息。


这里是一些示例。


GET / products: 列出所有的产品。
POST / products: 创建一个新的产品。
GET / products / {id}: 得到一个特殊产品的信息。
PUT / products / {id}: 更新一个特殊产品的信息。
PATCH / products / {id}: 更新一个特殊产品的部分信息，（信息主体里面需要提供，信息需要更新的部分）。
DELETE / products / {id}: 删除一个产品。
GET / productsgroup / {id} / employees: 列出一个已知产品组的所有产品。
DELETE / productsgroup / {id} / products / {id}: 删除一个已知产品组的特殊产品。





6. 过滤

如果记录数量巨大，服务器将无法返回给用户。API应当提供参数来过滤返回的结果。
这里是一些通用的参数。


? limit = 10: 明确返回的记录的数量。
? offset = 10: 详细说明返回记录的开始。
? page = 2 & pagesize = 100: 详细说明开始的几步，并且还有每页的记录数量。
sortby = name & order = asc:详细说明通过哪些属性去分理结果，还有分理顺序。
? productstype = 1: 明确过滤标准。





7. 状态码

服务器给用户返回的提示和状态码如下所示（方括号内是对应状态码的HTTP 动词）：



200 OK - [GET]: 服务器成功返回了用户请求的数据。此操作为幂等操作。

201 CREATED - [POST / PUT / PATCH]: 用户成功创建或修改数据。

202 Accepted - [*]: 提示一个请求在已经在背景队列中（非同步任务）。

204 NO CONTENT - [DELETE]: 用户成功的删除了数据。

400 INVALID REQUEST - [POST / PUT / PATCH]: 用户发送了一个错误请求，服务器没有修改数据或者进行任何其他的新操作，此操作为幂等操作。

401 Unauthorized - [*]: 提示用户没有得到许可（符号，用户名，密码错误）。

403 Forbidden - [*] 提示用户已被授权（与401相反），但是入口已被禁止。

404 NOT FOUND - [*]: 用户请求不存在，并且服务器没有任何操作。此操作是幂等的。

406 Not Acceptable - [GET]: 用户需求的格式不存在（例如，用户需要JSON 格式，但是只有XML格式）。

410 Gone - [GET]: 用户所需求的资源已被永久删除，并且无法找回。

422 Unprocesable entity - [POST / PUT / PATCH] 当创建一个对象的时候，出现验证错误。

500 INTERNAL SERVER ERROR - []: 内部服务器错误- []:服务器发生错误，用户无法得知即将发生的请求是否会成功。





8. 错误处理

如果状态码是4XX，你应该给用户返回了一条错误信息。一般来说，错误信息作为密钥名返回，错误信息即密钥的形式。

{
     error: "Invalid API key"
}




9. 返回

对于不同的操作，服务器返回结果给用户，应当满足以下具体要求。


GET / collection: 返回资源对象清单（队列）。
GET / collection / resource: 返回单独的资源对象。
POST / collection: 返回新生成的资源对象。
PUT / collection / resource: 返回完整的资源对象。
PATCH / collection / resource: 返回完整的资源对象。
DELETE / collection / resource: 返回一个空的文件。



正确示例

"tags": [
  {"id": "125", "name": "Environment"},
   {"id": "834", "name": "Water Quality"}
],


错误示例

用密钥代替字段
"tags": [
   {"125": "Environment"},
   {"834": "Water Quality"}
],




10. 超媒体API

The RESTful API 最好使用超媒体，它能在返回结果里面提供链接，链接到其他API，使用户不受检查，并且知道下一步计划。
例如，当一个用户发送一个请求到api.example.com的根目录下，你可以得到一个像这样的文件。

{"link": {
  "rel": "collection https://www.example.com/products",
  "href": "https://api.example.com/products",
  "title": "list of products",
  "type": "application / vnd.yourformat + json"
}}
以上的代码提示文件有一个链接属性，用户读到这个属性知道下一步调用哪个API，rel代表API和目前的URL的关系（聚合关系，并给出聚合的URL），href 代表API的路径，title 代表API的title, type 代表返回类型。
超媒体API设计叫做HATEOAS。Github's API就是这种设计，访问api.github.com得到所有可获的API的URL的列表。

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}
从以上你能够看到，如果你想要得到当前用户的信息，你应当访问api.github.com/user，然后得到以下结果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

以上代码提示，服务器给出一个提示和文件的URL。




参考

Wikipedia https://en.wikipedia.org/wiki/Representational_state_transfer
IETF definition https://tools.ietf.org/html/rfc7231
GitHub standard https://developer.github.com/v3/
Microsoft Standard https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md