可用性
API请求URI中如果存在特殊字符，需要进行转义编码
本条规则是MUST类型的基本规则，可保障API的高可用性。
某些字符，由于有特殊含义或者系统保留，容易被Web应用防火墙或者安全访问控制产品所阻断，导致URI调用不生效，因此不建议在URI中使用，如果必须要用需要用转义编码替换。
转义说明可参考：RFC 2396（Uniform Resource Identifiers (URI): Generic Syntax）。
API响应状态码应使用规范的HTTP状态码
本条规则是MUST类型的基本规则，可保障API的高可用性。
API响应所使用的状态码应使用规范的HTTP状态码，状态码所表达的状态与API响应状态保持一致。
具体的HTTP状态码使用可参考RFC 7231（Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content），常用状态码如表1所示。
状态码 |
状态码表示 |
状态码详细信息 |
|---|---|---|
200 |
OK |
执行成功，如：查询成功响应。 |
201 |
Created |
创建成功，如：创建记录成功。 |
400 |
Bad Request |
客户端请求语义有误，当前请求无法被服务器理解或请求参数有误。 |
401 |
Unauthorized |
当前请求需要用户验证，需要用户提供Token进行认证。 |
403 |
Forbidden |
禁止访问某些资源，如权限不足时无法查询对应的信息。 |
404 |
Not Found |
无法找到对应资源，如资源不存在。 |
405 |
Method Not Allowed |
HTTP方法不能被用于请求相应的资源如：HTTP方法要求POST方法，请求中使用了GET方法。 |
406 |
Not Acceptable |
请求资源的内容特性无法满足请求头中的条件。 |
413 |
Payload Too Large |
请求提交的实体数据大小超过了服务器够处理的范围。 |
414 |
URI Too Long |
请求的URI长度超过了服务器能够解释的长度。 |
415 |
Unsupported Media Type |
当前请求的方法和所请求的资源，请求中提交的实体并不是服务器中所支持的格式。 |
500 |
Internal Server Error |
服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理。通常是服务器内部产生了错误，导致处理失败。 |
502 |
Bad Gateway |
代理服务器尝试执行请求时，从上游服务器接收到无效的响应。 |
API请求设置媒体类型和编码格式，响应内容格式需与响应设置媒体类型和编码格式一致
本条规则是MUST类型的基本规则，可保障API的高可用性。
- 在API请求中对媒体类型和编码格式的正确定义有助于服务端对请求体进行格式校验，避免出现因请求消息体格式错误导致的执行异常。
- API响应内容格式需要与响应设置媒体类型和编码格式一致。在API响应中对媒体类型和编码格式的正确定义有助于服务端对请求体进行格式校验，避免出现因请求消息体格式错误导致的执行异常。
- API的默认媒体类型为“Content-Type: application/json”和“charset=UTF-8”。
- 当使用非application/json媒体类型时，建议根据情况选择合适的媒体格式，具体情况如表2所示。
表2 常见的媒体类型 分类
场景
媒体类型
文件上传/下载类
文件上传下载类的接口，直接传递的是文件内容。
须知：不建议使用该API进行文件传输。
application/octet-stream
表单提交
主要用于界面表单提交，该方法目前已经不属于主流提交手段，建议使用JSON格式进行表单提交。
application/x-www-form-urlencoded
混合多部分类型
传递混合多部分内容类的接口，比如既有文本内容，表单内容，也有二进制文件的。
multipart/form-data
SOAP协议
调用以SOAP协议的WebService。
text/xml或application/xml
纯文本类型
仅传递纯文本内容。
text/plain
