RESTFul API最好实践

RESTful API 概述

基本观点

REST 英文全称：Representational State Transfer，直译为：表现层状况转移。初次是由Roy Thomas Fielding在他2000年的博士论文中提出。

REST是一种形貌收集中client和server之间的资本交互体式格局。

而RESTful API就是完整遵照REST体式格局的一套API设想范例，简朴来讲，经由过程API来形貌资本的接见体式格局：

• 经由过程HTTP URL形貌接见什么资本
• 经由过程HTTP METHOD形貌对资本的交互体式格局
• 经由过程HTTP CODE形貌资本的交互结果

幂等性

幂等性(Idempotence)自身是一个数学观点，在HTTP/1.1范例中幂等性是指

Methods can also have the property of “idempotence” in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request.

假如某个要领挪用一次或屡次发生的副作用是雷同的，那末这个要领具有幂等性。

比方在HTTP中运用GET猎取某个资本，不管挪用多少次，发生的分外结果都是从服务器猎取资本，所以GET体式格局具有幂等性。

而POST要领用于在服务器上建立一个资本，由于终究建立的结果每次都是差别的，所以POST不具有幂等性。

然则PUT要领倒是幂等的，由于每次挪用发生的结果都是对资本举行更新。

平安要领

平安要领是指不修正资本的 HTTP 要领。比方，当运用 GET 或许 HEAD 作为资本 URL，都必须不去转变资本的表现情势。

注重：平安要领并非指服务器上的资本完整稳定，而是指资本的表现情势。

比方GET要领致使数据上报，关联的一些数据纪录等，他实际上是转变了服务器上的某些附加资本的，然则这并不会转变资本的表现情势。

HTTP要领特征概览

HTTP Method	幂等性	平安性
OPTIONS	yes	yes
GET	yes	yes
HEAD	yes	yes
PUT	yes	no
POST	no	no
DELETE	yes	no
PATCH	no	no

RESTful API设想划定规矩

HTTP URL

HTTP URL只用于形貌接见的资本，而不应当包括对资本的交互体式格局。HTTP URL的Best Practice:

• 将API布置在专用的域名上，如api.example.com
• 不运用任何大写字符
• 不运用下划线_，可运用中划线-替代来支解单词
• 参数列表要举行URL编码
• 不应当涌现形貌资本交互体式格局的动词，应只管运用形貌资本的名词
• URI中的名词示意资本鸠合，应当运用复数情势
• 应当防止资本层级太深，可以恰当运用参数削减层级
• 运用斜杆/示意资本之间的层级关联
• 在URI的末端防止运用/
• 防止在URI中运用文件扩展名
• 假如有必要，须要在URI中增加版本号标识

相应的示例以下：

// 下面列出几个bad case以及修正要领
/userPost        // should use uppercase letter
-> /user-posts

/user/post       // should use resource plural 
-> /users/posts

/users/addPost   // avoid using react verb
-> POST /users/posts

/users/posts/    // remove the last `/`
-> /users/posts

/users/posts/picture.gif  // remove the extension `.gif`  
-> /users/posts/picture

/users/recent_posts       // use `-` replace `_`
-> /users/recent-posts

/users/posts?title=up up  // param encode
-> /users/posts?name=up%20up

/users/posts/games/picture/today  // avoid too deep relations
-> /users/posts/picture?type=game&time=today 

/users/learning-posts     // add version tag
-> /v1/users/learning-posts

补充申明：

• /users/search像这个URI，虽然包括动词search，然则search并没有形貌对资本的交互体式格局，所以这类URI也是可以的
• /users/posts, /user-posts如许的两个URI，第一个形貌了层级关联，第二个没有，然则两个URI任然可以很明白的示意资本，并没有谁最好的说法，可以连系地点团队的定名习气等来拔取

HTTP METHOD

严厉运用下面的HTTP要领来形貌资本CURD操纵体式格局，应当只管防止在POST体式格局中删除资本等违犯直觉的操纵：

• GET: 查询资本
• POST: 建立资本
• PUT: 更新资本
• DELETE: 删除资本

关于一些GET中一次性猎取大批资本的状况下，比方猎取一万个指定资本的状况，可能会涌现HTTP URL凌驾长度限定，这个时刻可以分批猎取。

虽然新版的HTTP规范支撑在GET要求中传送body，然则一些收集服务器并不能很好的支撑，应当郑重运用。

别的关于庞杂的资本猎取，应当供应通用的资本挑选、排序、分页、字段挑选等功能支撑，并一致参数范例。比方：

Filtering:
GET /cars?color=red Returns a list of red cars
GET /cars?seats<=2 Returns a list of cars with a maximum of 2 seats

Sorting:
GET /cars?sort=-manufactorer,+model

Field selection:
GET /cars?fields=manufacturer,model,id,color

Paging:
GET /cars?offset=10&limit=5

掩盖HTTP要领
一些HTTP客户端只支撑GET和POST要求。为了可以增强这些客户端的接见才能，API须要可以掩盖HTTP要领。

只管这里没有任何强迫的规范，但盛行的做法是API会吸收一个要求头X-HTTP-Method-Override，它的值可所以PUT、PATCH或许DELETE三者之一。

注重，用来掩盖HTTP要领的header只能在POST要求中被接收。GET要求永久不能修正服务器上的数据。

HTTP RESPONSE

关于HTTP要求的返回值，有以下几点Best Practice:

• 采纳花样化返回数据，引荐json
• 充分利用HTTP状况码来形貌毛病范例
• 范例返回数据的一致花样，以及细分毛病范例和提醒
• 应当只管返回有效的毛病信息和提醒，唯一的毛病码

经常使用的HTTP状况码：

• 200 OK - 对胜利的GET、PUT、PATCH或DELETE操纵举行相应。也可以被用在不建立新资本的POST操纵上
• 201 Created - 对建立新资本的POST操纵举行相应。应当带着指向新资本地点的Location header)
• 204 No Content - 对不会返回相应体的胜利要求举行相应（比方DELETE要求）
• 304 Not Modified - HTTP缓存header见效的时刻用
• 400 Bad Request - 要求非常，比方要求中的body没法剖析
• 401 Unauthorized - 没有举行认证或许认证不法。当API经由过程浏览器接见的时刻，可以用来弹出一个认证对话框
• 403 Forbidden - 当认证胜利，然则认证过的用户没有接见资本的权限
• 404 Not Found - 当一个不存在的资本被要求
• 405 Method Not Allowed - 所要求的HTTP要领不允许当前认证用户接见
• 410 Gone - 示意当前要求的资本不再可用。当挪用老版本API的时刻很有效
• 415 Unsupported Media Type - 假如要求中的内容范例是毛病的
• 422 Unprocessable Entity - 用来示意校验毛病
• 429 Too Many Requests - 由于要求频次到达上限而被谢绝接见

参考文档

• https://en.wikipedia.org/wiki/Representational_state_transfer
• https://restfulapi.net/resource-naming/
• https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
• https://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/
• https://blog.florimond.dev/restful-api-design-13-best-practices-to-make-your-users-happy