更新时间:2023-09-27 GMT+08:00
分享

可用性

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所示。

表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

相关文档