1、REST的定义
请参考论文:https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
2、API文档编写语义:
本文档中的关键字:
必须-MUST,
不得-MUST NOT,
必需-REQUIRED,
应该-SHALL,
不应该-SHALL NOT,
应该-SHOULD,
不应该-SHOULD NOT,
推荐-RECOMMENDED,
可能-MAY
可选-OPTIONAL
3、请求类型定义
请求类型(Method Type)根据业务动作进行合理选择,不能全都使用 POST 方式,如下:
PUT:这个请求的含义就是推送某个资源到服务器,更新整个资源
PATCH: 更新局部资源
POST:向服务器提交一个全新且唯一的资源(无法幂等)
DELETE:这个请求会删除服务端的某个资源
GET:向服务器获取资源
HEAD: 大的语义上和GET请求是类似,只是只需要返回响应头信息即可,通常用于客户端用于资源存在性等判断
TRACE:这是一个将服务器所收到请求回显给客户端的请求,主要用于测试或诊断。
OPTIONS:返回对于指定资源,可以使用的请求类型。这个方法在正常工作中使用的比较少,它一般用途是,在正式请求资源之前,先看看
对于资源都可以使用那些请求;
CONNECT :请求HTTP/1.1协议中预留给能够将连接改为管道方式的代理服务器。通常用于SSL加密服务器的链接
4、请求状态码
根据实际业务场景,严格规范定义并正确使用请求状态码,客户端的每一次请求, 服务器端必须给出回应,回应一般包括HTTP状态码 和 数据两部分
1xx: 信息,请求收到了,继续处理。
2xx: 代表成功. 行为被成功地接收、理解及采纳。
3xx: 重定向。
4xx: 客户端错误,请求包含语法错误或请求无法实现。
5xx: 服务器端错误.
2xx 状态码
200 OK [GET]: 服务器端成功返回用户请求的数据。
201 CREATED [POST/PUT/PATCH]: 用户新建或修改数据成功。
202 Accepted 表示一个请求已经进入后台排队(一般是异步任务)。
204 NO CONTENT -[DELETE]: 用户删除数据成功。
4xx 状态码
400:Bad Request - [POST/PUT/PATCH]: 用户发出的请求有错误,服务器不理解客户端的请求,未做任何处理。
401: Unauthorized; 表示用户没有权限(令牌、用户名、密码错误)。
403:Forbidden: 表示用户得到授权了,但是访问被禁止了, 也可以理解为不具有访问资源的权限。
404:Not Found: 所请求的资源不存在,或不可用。
405:Method Not Allowed: 用户已经通过了身份验证, 但是所用的HTTP方法不在它的权限之内。
406:Not Acceptable: 用户的请求的格式不可得(比如用户请求的是JSON格式,但是只有XML格式)。
410:Gone - [GET]: 用户请求的资源被转移或被删除。且不会再得到的。
415: Unsupported Media Type: 客户端要求的返回格式不支持,比如,API只能返回JSON格式,但是客户端要求返回XML格式。
422:Unprocessable Entity: 客户端上传的附件无法处理,导致请求失败。
429:Too Many Requests: 客户端的请求次数超过限额。
5xx 状态码
500:INTERNAL SERVER ERROR; 服务器发生错误。
502:网关错误。
503: Service Unavailable 服务器端当前无法处理请求。
504:网关超时。