在上一篇RESTful系列文章中，笔者介绍了RESTful API定义及管理。接下来，本篇文章将阐释RESTful API设计规范：一、目标二、URL定义格式三、资源表述四、 资源名和资源值五、统一接口六、响应状态码七、批量操作八、重载POST九、自定义报头十、授权
目录
一、目标
- 明确对外提供服务的API格式
- 明确系统资源划分的方式
- 明确URL定义格式
- 明确API请求和响应信息格式
- 明确错误码定义格式
二、URL定义格式
URI组成部分：
https://zh.wikipedia.org/wiki/%E7%BB%9F%E4%B8%80%E8%B5%84%E6%BA%90%E6%A0%87%E5%BF%97%E7%AC%A6
hierarchical part
┌───────────────────┴─────────────────────┐
authority path
┌───────────────┴───────────────┐┌───┴────┐
abc://username:password@example.com:123/path/data?key=value&key2=value2#fragid1
└┬┘ └───────┬───────┘ └────┬────┘ └┬┘ └─────────┬─────────┘ └──┬──┘
scheme user information host port query fragment
2.1 Scheme
客户端在通过API与服务端进行通信时，必须使用HTTPS协议，才能保证报文安全，除非调试接口，否则严禁使用HTTP。
2.2 Port
各微服务对外提供服务时需要统一API端口，如HTTPS统一使用443，也可以自定义使用其他端口。
2.3 Path
前缀
path部分以api开头，后跟微服务名、版本及模块名或资源地址，示例：
- https://host:port/api/message/v1/notification
message表示消息微服务。
v1表示版本，以字母v开头，后跟数字，API若无法保持兼容，或无法在旧API上进行扩展，则应使用新版本API。
notification表示微服务内部的一个模块或者资源地址，名字及层级均可自定义，具体见下一节资源地址。
资源地址
参考文档RESTful API设计基础知识-资源分类和RESTful API设计基础知识-URI设计
在路径设计中需要遵守下列约定：
- 资源命名全部小写且易读，可使用连字符（-）或下划线（_）进行分隔
- 资源名不可以使用 (.) 和 (..)，会被浏览器识别为相对路径。
- 资源的命名需要符合RESTful风格，只有算法资源中可以存在动词，否则只能使用名词；
- 算法资源：在数据集上执行算法的结果的资源，注重从该动作的结果方面来考虑(如"地图上符合搜索条件的地点")。
- 其他资源：为特别目的专门预定义的一次性资源、服务暴露的每一个对象所对应的资源。
- 路径部分使用斜杠分隔符（/）来表达层次结构：/parent/child。
- 路径部分使用逗号（,）来表示非层次结构：/parent/child1,child2。
- 采用OAS 3.0描述的API，必须遵循路径参数序列化规则：Parameter Serialization，统一使用下图红框中的风格。
为防止URL过长被截断，服务端收到请求后需要检测序列化后的路径参数是否和请求body中对应字段匹配（个数是否相等、内容是否相同），不匹配则抛错处理。
示例如下：
- https://host:443/api/micro-service/v1/file/{docid}/download-info
- https://host:443/api/micro-service/v1/earth/37.0,-95.2
- https://host:443/api/micro-service/v1/file/items_count,items
2.4 Query
若路径变量与标点符号均解决不了问题，或者如果你要往一个算法里代入参数的话，那么可以采用查询变量(query variables)。
如果两个URIs只在查询变量上有差别，这表明它们只是为同一算法设置了不同的参数。
用查询变量来表达算法的输入：GET /search?q=jellyfish&start=20。
参数设计需要遵守下列约定：
- 参数名使用下划线分隔小写字母的方式命名。
- 采用OAS 3.0描述的API，必须遵循查询参数序列化规则：Parameter Serialization，统一使用下图红框中的风格
示例如下：
- https://host:443/api/micro-service/v1/department?offset=10&limit=100
- https://host:443/api/micro-service/v1/department?department_type=1&department_type=2&department_type=3
三、资源表述
请求body、响应body中的数据，即是资源表述，描述资源地址所指向数据的样子，格式为json，只允许使用object和array，不允许直接请求或响应string、number等。
所有请求和响应的"Content-Type"必须和实际的数据格式保持一致，保证调试工具(如：Postman)、SDK生成工具、文档生成工具能够正确识别接口。
四、 资源名和资源值
资源地址、资源表述、query中的资源名和资源值均需遵循以下规则
4.1 命名规范
资源地址中的资源名，采用小写字母，使用连字符（-）或下划线（_）分隔；
资源表述、query中的资源名，采用小写字母，使用下划线（_）分隔；
若同一资源名会出现在资源地址、资源表述、query中，资源名必须一致，即统一使用下划线（_）分隔。
4.2 时间戳格式
资源值为时间戳时，统一使用RFC3339格式。
4.3 枚举类型定义规范
资源值为枚举类型时，统一使用小写字符串，如有多级的情况，使用( . )进行层级区分。
|
|
4.4 标准字段
使用一组标准资源名和资源值定义来确保相同的概念在不同API中具有相同的名称和语义。
4.5 通用参数名
现有已知通用的参数名如下表所示。
- 分页搜索
| 使用位置 | 参数名 | 参数类型 | 描述 | 用法 |
|---|---|---|---|---|
| query | offset | int64 | 开始响应的项目的偏移量 | 默认为0（>=0），小于0则抛错 未传offset字段，或未设置offset的值时，取默认值 |
| limit | int64 | 每页最多可返回的项目数 | 默认20（可根据功能修改默认值），范围为 [1, 1000]，超出范围则抛错 未传limit字段，或未设置limit的值时，取默认值 |
|
| direction | string | 排序结果方向 | 可选值：asc、desc | |
| sort | string | 排序类型 | ||
| response body | entries | Array of objects | 条目列表 | {
"entries": [
{...},
{...}
],
"total_count": 95
} |
| total_count | integer <int64> | 总条数(忽略offset和limit) |
4.6 单复数
表示多个数据的集合的资源名应使用复数，如：
- 若干个文件，/files
- 某个具体文件，/files/{id}
五、统一接口
对于资源的具体操作类型，由HTTP方法表示：
- GET：用于获取关于资源的信息。
- HEAD：与GET类似，但响应时只返回首部。
- PUT：用于设定资源状态。服务器根据客户端发送请求时提供的表示来创建或修改资源的状态。
- POST：用于新建从属资源，或用于往已有资源的状态里添加数据。
- DELETE：用于删除资源。
其中，
- 获取资源信息使用GET方法。
- 新建/更新资源根据自身情况选择PUT或POST方法。
- 删除资源使用DELETE方法。
HTTP方法和路径可能的组合如下：
| 请求方法 |
URL |
描述 |
|---|---|---|
| GET | /department | 获取所有部门信息 |
| POST | /department | 新增一个新的部门 |
| GET | /department/{departmentid} | 获取指定部门详细信息 |
| PUT | /department/{departmentid} | 更新指定部门信息 |
| DELETE | /department/{departmentid} | 删除指定部门 |
对HTTP方法的使用，一定要遵循相应方法的安全性和幂等性
最低0.47元/天 解锁文章
211
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
