RESTful API设计

1.URL设计

五种 HTTP 方法对应 CRUD 操作(GET、POST、PUT、PATH、DELETE)。
动词+宾语结构:GET/articles
动词覆盖:POST模拟(PUT、PATH、DELETE),设置X-HTTP-Method-Override: PUT。
操作读取集合,复数URL
宾语是名词
避免多级 URL
GET /articles?published=true

2.状态码

五类状态码:1相关信息,2操作成功,3重定向,4客户端错误,5服务器错误

API 不需要1xx状态码。

200 OK,(GET,PATCH,PUT)
201 Created(生成了新的资源),POST
202 Accepted(服务器已经收到请求,但还未进行处理,常用异步操作)
204 No Content(资源已经不存在),DELETE
301(永久重定向) 浏览器会直接跳转,API不用考虑
302,307 GET(暂时重定向)浏览器会直接跳转,API不用考虑
303 POST/PUT/DELETE(参考另一个 URL)浏览器不会自动跳转,而会让用户自己决定下一步
400 Bad Request:服务器不理解客户端的请求,未做任何处理
401 Unauthorized:用户未提供身份验证凭据,或者没有通过身份验证。
403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。
404 Not Found:所请求的资源不存在,或不可用。
405 Method Not Allowed:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。
410 Gone:所请求的资源已从这个地址转移,不再可用。
415 Unsupported Media Type:客户端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客户端要求返回 XML 格式。
422 Unprocessable Entity :客户端上传的附件无法处理,导致请求失败。
429 Too Many Requests:客户端的请求次数超过限额。
500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。
503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。

3.服务器响应

服务器返回JSON对象,服务器响应时,HTTP 头的Content-Type属性要设为application/json。
客户端请求时,HTTP 头的ACCEPT属性也要设成application/json。

发生错误时,不要返回 200 状态码,状态码反映发生的错误,具体的错误信息放在数据体里面返回

提供URL链接,例如:api.github.com 一步步查找就可以了(最好将相关链接与其他属性分开)。

Reference:
https://blog.florimondmanca.com/restful-api-design-13-best-practices-to-make-your-users-happy
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html