RESTFul接口设计指南

概述
REST 一词是由 Roy Fielding 博士于 2000 年在他的博士论文[ Architectural Styles and the Design of Network-based Software Architecture|https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm] 中提出的，实际指一种有助于创建和组织分布式系统的架构风格。它并不是一个标准或准则，而是一种基于资源的架构风格。
以 REST 风格构建的系统将在性能、组件交互的可扩展性、接口的简单性、可移植性、可靠性、可见性等多个方面得到提升和优化。
注：Roy Fielding 是 HTTP 协议（1.0 版和 1.1 版）的主要设计者、Apache 服务器软件的作者之一、Apache 基金会的第一任

设计指南
RESTful API的设计概括起来主要包含以下几个要点：用 URL 定位资源，用 HTTP 动词描述操作，实现资源的状态转换。
美云智数RESTful接口设计在业界RESTful API的设计规范基础上，主要做了以下几点约定和补充：

HTTP动词只允许使用5个，分别是GET、POST、PUT、PATCH、DELETE。
返回格式统一使用JSON表示，并且统一首层数据格式。
业务处理状态码不直接使用HTTP状态码来表示，而是通过返回字段code来表示。

总体上依然遵循RESTful API设计规范，具体如下：

设计原则
任何一个API都会包含URL，入参，响应三大部分，以下是一个RESTful API在设计上的要求：
URL：
{HTTP method} https://xxx.meicloud.com/\{version}/{resource}?{query-parameters}
入参：
Header参数
Path参数
Query参数
Body参数
响应：
HTTP状态码
错误码
提示信息
返回数据
说明：

传输协议：https，为接口的安全提供了保障，可以有效防止通信被窃和篡改。注意：非https的API调用，不要重定向到 https，而要直接返回调用错误以禁止不安全的调用。
请求方法：{HTTP method}，只使用5个常见HTTP动词（GET,POST,PUT,PATCH,DELETE）实现对资源的操作，详见【Http Method使用规范】章节。
Header参数：主要包含调用 API 所需要使用的访问凭证（access_token）以及 HTTP Content-Type。
版本：{version}，指定API的版本信息，OpenAPI必须指定版本，详见【API版本管理规范】章节。
资源：{resource}，表示要操作的资源，用复数表示，例如：用户，用/users表示,；某用户的兴趣爱好，用/users/1/hobbies表示，等等。整个URL路径只能有名词组成，不应该包含动词。
Path参数：URL中的参数，这部分参数需要放置在 URL 中，在文档中一般以{ }表示。
Query参数：{query-parameters}，这部分参数在 URL 后使用?进行连接，多个查询参数以&分割。
Body参数：放在 HTTP 请求的Body 中，统一使用 JSON 格式。
HTTP状态码：跟标准的RESTful规范有所不一样，这里的HTTP状态码只反映HTTP请求的状态，跟业务无关，详见附录【HTTP状态码】。
错误码：字段名为code，描述业务请求的响应状态，0表示成功，其他返回码详见【错误码设计规范】。
提示信息：字段名为message，跟返回码对应的提示信息。
返回数据：字段名为data，服务器返回的数据，可以是基本类型、对象、集合格式。
Http Method使用规范
为了简化理解，我们约定只使用5个HTTP方法，具体如下：





GET

获取资源，单个或多个

是

GET /users #获取所有用户信息
GET /users/1 #获取id为1的用户

POST

创建资源

否

POST /users #新增一个用户

PUT

更新资源，客户端提供完整的资源数据

是

PUT /users/1 #覆盖用户信息

PATCH

更新资源，客户端提供部分的资源数据

否

PATCH /users/1 #修改用户信息

DELETE

删除资源

是

DELETE /users/1 #删除用户

更多示例可以参考主流开放API文档：

GitHub REST API : https://docs.github.com/cn/rest
API版本管理规范
API版本采用大版本号+小版本号组合的形式，例如v1.0、v2.1。

小版本号升级（例如从1.0升级到1.1）意味着发布了不兼容历史版本的API升级。
大版本号升级时（例如从1.0升级到2.0），上一个版本的API将在一段时间后停止支持。接口文档将取消上一个大版本API的入口。


错误码设计规范
全局错误码有两个：0-成功，1-未知异常，其他错误码统一格式为：产品简称_模块简称_5位异常码。

产品简称：产品英文简称，以公司统一定义的为准。
模块简称：根据各产品实际需要进行定义，主要作用是方便问题溯源，快速找到责任人。不建议按照微服务定义，因为微服务的粗细划分会根据业务变化有所调整，但是错误码定义不会发生变化。公共模块定义为：COMMON。
异常码：1位错误分类码+4位流水号。
错误分类码规范：
1-系统异常，如：系统限流，系统内存耗尽，数据连接池已满等；
2-业务异常，如：手机号重复注册；
3-输入异常，如：邮件格式不正确；
4-第三方调用异常，如：OA接口请求异常；
5-9为预留异常码，根据未来的需要统一定义。

错误码示例：

0-成功
1-未知异常；【提示语由UED设计】
IAM_ORG_20001 已经启用的组织不能删除，如需停用可以使用[禁用]功能；

IAM_ORG_30001 组织类型不能为空；
IAM_ORG_30002 组织名称不能重复；
IAM_COMMON_10000 对象存储服务访问异常；
IAM_COMMON_30001 导入文件不能为空；


分页查询规范


分页参数跟其他参数放同一个地方，方便后端统一DTO接受，命名如下：pageNum：第几页，从1 开始pageSize：单页记录数



分页相关字段放到data的下一层，命名如下：pageNum：第几页，从1开始pageSize：单页记录数total：记录总数list:[] 列表数据，为空则返回空数组而不是null



附录1：RESTful API标准理论
作者论文：https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

附录2：HTTP状态码
HTTP 状态码由三个十进制数字组成，第一个十进制数字定义了状态码的类型。响应分为五类：信息响应(100–199)，成功响应(200–299)，重定向(300–399)，客户端错误(400–499)和服务器错误 (500–599)：

分类

分类描述

1**

信息，服务器收到请求，需要请求者继续执行操作

2**

成功，操作被成功接收并处理

3**

重定向，需要进一步的操作以完成请求

4**

客户端错误，请求包含语法错误或无法完成请求

5**

服务器错误，服务器在处理请求的过程中发生了错误

HTTP状态码列表:

状态码

状态码英文名称

中文描述

100

Continue

继续。客户端应继续其请求

101

Switching Protocols

切换协议。服务器根据客户端的请求切换协议。只能切换到更高级的协议，例如，切换到HTTP的新版本协议



200

OK

请求成功。一般用于GET与POST请求

201

Created

已创建。成功请求并创建了新的资源

202

Accepted

已接受。已经接受请求，但未处理完成

203

Non-Authoritative Information

非授权信息。请求成功。但返回的meta信息不在原始的服务器，而是一个副本

204

No Content

无内容。服务器成功处理，但未返回内容。在未更新网页的情况下，可确保浏览器继续显示当前文档

205

Reset Content

重置内容。服务器处理成功，用户终端（例如：浏览器）应重置文档视图。可通过此返回码清除浏览器的表单域

206

Partial Content

部分内容。服务器成功处理了部分GET请求



300

Multiple Choices

多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择

301

Moved Permanently

永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。今后任何新的请求都应使用新的URI代替

302

Found

临时移动。与301类似。但资源只是临时被移动。客户端应继续使用原有URI

303

See Other

查看其它地址。与301类似。使用GET和POST请求查看

304

Not Modified

未修改。所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。客户端通常会缓存访问过的资源，通过提供一个头信息指出客户端希望只返回在指定日期之后修改的资源

305

Use Proxy

使用代理。所请求的资源必须通过代理访问

306

Unused

已经被废弃的HTTP状态码

307

Temporary Redirect

临时重定向。与302类似。使用GET请求重定向



400

Bad Request

客户端请求的语法错误，服务器无法理解

401

Unauthorized

请求要求用户的身份认证

402

Payment Required

保留，将来使用

403

Forbidden

服务器理解请求客户端的请求，但是拒绝执行此请求

404

Not Found

服务器无法根据客户端的请求找到资源（网页）。通过此代码，网站设计人员可设置"您所请求的资源无法找到"的个性页面

405

Method Not Allowed

客户端请求中的方法被禁止

406

Not Acceptable

服务器无法根据客户端请求的内容特性完成请求

407

Proxy Authentication Required

请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权

408

Request Time-out

服务器等待客户端发送的请求时间过长，超时

409

Conflict

服务器完成客户端的 PUT 请求时可能返回此代码，服务器处理请求时发生了冲突

410

Gone

客户端请求的资源已经不存在。410不同于404，如果资源以前有现在被永久删除了可使用410代码，网站设计人员可通过301代码指定资源的新位置

411

Length Required

服务器无法处理客户端发送的不带Content-Length的请求信息

412

Precondition Failed

客户端请求信息的先决条件错误

413

Request Entity Too Large

由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息

414

Request-URI Too Large

请求的URI过长（URI通常为网址），服务器无法处理

415

Unsupported Media Type

服务器无法处理请求附带的媒体格式

416

Requested range not satisfiable

客户端请求的范围无效

417

Expectation Failed

服务器无法满足Expect的请求头信息



500

Internal Server Error

服务器内部错误，无法完成请求

501

Not Implemented

服务器不支持请求的功能，无法完成请求

502

Bad Gateway

作为网关或者代理工作的服务器尝试执行请求时，从远程服务器接收到了一个无效的响应

503

Service Unavailable

由于超载或系统维护，服务器暂时的无法处理客户端的请求。延时的长度可包含在服务器的Retry-After头信息中

504

Gateway Time-out

充当网关或代理的服务器，未及时从远端服务器获取请求

505

HTTP Version not supported

服务器不支持请求的HTTP协议的版本，无法完成处理