RESTFul API最好实践
2019-11-18杂谈搜奇网32°c
A+ A-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