API 规范
2022-07-20 14:40:50 1 举报AI智能生成
API接口规范
作者其他创作
大纲/内容
API规范
URI
格式: https://{host}:{port}/{application}/api/{version}/{resources}
字母一律小写，使用横线 '-' 作为连字符，不允许使用下划线
正确示例： /api/v1.0/automation/sap-jobs
正确示例： /api/v1.0/automation/sap-jobs
使用/来表示资源的层级关系
资源统一使用复数形式
只有 POST 时, URI 才能使用动词, 且只应放在最后
清晰易懂，没有歧义，并避免过多的路径嵌套
不应以 "/" 结尾
使用-来分隔一些单词
, 或 ; 可以用来表示同级资源的关系
有时候我们需要表示同级资源的关系时，可以使用,或;来进行分割。例如哪天github可以比较某个文件在随意两次提交记录之间的差异，或许可以使用/git/git /block-sha1/sha1.h/compare/e3af72cdafab5993d18fae056f87e1d675913d08;bd63e61bdf38e872d5215c07b264dcc16e4febca作为URI。 不过，现在github是使用…来做这个事情的，例如/git/git/compare/master…next。
长度应控制在 2083 个字符以内
必须加入 API 版本:
格式为 v<大版本号>.<小版本号>, 如: v1.2
大版本号从 1 开始, 小版本号从 0 开始, 即最小版本号为 v1.0
协议变化时, 当且仅当新协议向后兼容时, 增加小版本号, 否则, 应增加大版本号, 并重置小版本为 0
只是 API 内部实现的增强，而不影响 API 交互结构时，不需要改变版本号。
API 升级时, 新旧版本必须存在适当的共存期, 不得使用覆盖的方式开发和升级
格式为 v<大版本号>.<小版本号>, 如: v1.2
大版本号从 1 开始, 小版本号从 0 开始, 即最小版本号为 v1.0
协议变化时, 当且仅当新协议向后兼容时, 增加小版本号, 否则, 应增加大版本号, 并重置小版本为 0
只是 API 内部实现的增强，而不影响 API 交互结构时，不需要改变版本号。
API 升级时, 新旧版本必须存在适当的共存期, 不得使用覆盖的方式开发和升级
不应包含资源的扩展名（以 Content-Type 协商的数据格式为准）
错误示例： GET /automation/api/v1.0/servers.json
错误示例： GET /automation/api/v1.0/servers.json
当是参数是对资源的限定时, 应使用路径变量, 如资源的 ID
正确示例： PUT /automation/api/v1.0/servers/{serverId}
正确示例： PUT /automation/api/v1.0/servers/{serverId}
URI 可以使用查询字段作为过滤条件，并在 API 文档中明确说明每个字段的含义、格式、使用场景等。
正确示例：GET /automation/api/v1.0/servers?page=1&size=20
正确示例：GET /automation/api/v1.0/servers?page=1&size=20
总结
全小写，使用横线'-'作为连字符
只有post 请求中，uri 才可以使用
不以"/" 结尾
资源统一使用复数形式
method
只允许使用的动词
GET
不可用 GET 来创建、删除、修改资源等对持久化资源/服务器状态有副作用的场景
通常使用 GET 来查询资源; 仅当一些请求体较大较复杂的情况需使用 POST
POST
既然PUT和POST操作都是向服务器端发送数据的，那么两者有什么区别呢。POST主要作用在一个集合资源之上的（url），而PUT主要作用在一个具体资源之上的（url/xxx），通俗一下讲就是，如URL可以在客户端确定，那么可使用PUT，否则用POST。
PATCH
PUT
DELETE
OPTIONS
HEAD
请求头
content-type
Accept
Authorization
请求体
数据交换有哪些要求
请求/响应报文使用 JSON 报文（RFC7159）, 编码为 UTF-8
服务端返回数据应使用统一的外层结构
应使用 小驼峰式命名法, 参考: 命名的礼仪
不可强制要求客户端传送空字段
避免冗余数据的来回传递
服务端/客户端不可对端传来的数据都应有一定的容错和忽略机制, 且不应依赖字段的顺序
数据格式遵从 2.12 Data Formats, 日期时间统一采用：
ISO 标准时间格式，时区为 UTC (GMT +0 ) 时区，如：2020-01-02T19:55:46.123Z
时间戳格式, 单位为毫秒, 类型为长整型 (long/bigint/int64)，由对端自行格式化
ISO 标准时间格式，时区为 UTC (GMT +0 ) 时区，如：2020-01-02T19:55:46.123Z
时间戳格式, 单位为毫秒, 类型为长整型 (long/bigint/int64)，由对端自行格式化
引申
时间戳是否存在时区的问题：
时间戳的定义：从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数。
从定义中发现，时间戳规定了地点（相当于时区）和起始时间，所以不存在时区问题。
时间戳的定义：从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数。
从定义中发现，时间戳规定了地点（相当于时区）和起始时间，所以不存在时区问题。
API 提供方可选择性支持其他数据格式 , 并通过 Content-Type 来协商。
分页及带排序查询api如何写
示例
/api/v1/servers?page=1&size=20&sort=ip,asc&sort=name,desc
page
从 1 开始, 代表第一页, 默认值为 1
size
每页大小
size 无效时可使用默认值
须视情况, 限制最大返回数量
sort
值格式为: "字段名,方向", 以逗号分割, 如按照 name 升序则是 "name,asc", 降序是 "name,desc"
支持多个排序字段是, 以第一个 sort 为主排序规则, 其次是第二个, 依次类推
响应头
响应体
结构
success
Boolean
是
标识是否调用成功。如果正确使用HTTP返回码，该字段其实不需要。但为了前端调用的便利性，目前该字段依然强制要求。
是
标识是否调用成功。如果正确使用HTTP返回码，该字段其实不需要。但为了前端调用的便利性，目前该字段依然强制要求。
code
String
是 (失败时)
成功时，补充性信息
出错时，服务端返回的错误编码（不同于 HTTP 状态码）。
是 (失败时)
成功时，补充性信息
出错时，服务端返回的错误编码（不同于 HTTP 状态码）。
message
String
是 (失败时)
成功时，补充性的信息
出错时，服务端给出的错误信息及排错建议
应尽可能根据 Accept-Language 进行国际化, 否则使用缺省语言
是 (失败时)
成功时，补充性的信息
出错时，服务端给出的错误信息及排错建议
应尽可能根据 Accept-Language 进行国际化, 否则使用缺省语言
data
Object / Array
是 (成功时)
服务端成功响应请求后，返回给客户端的数据。以 JSON 对象或对象列表方式返回。针对每一个API，需要具体定义。定义规范同请求体数据结构。
是 (成功时)
服务端成功响应请求后，返回给客户端的数据。以 JSON 对象或对象列表方式返回。针对每一个API，需要具体定义。定义规范同请求体数据结构。
timestamp
long
是
时间戳（UTC）, 精确到毫秒
是
时间戳（UTC）, 精确到毫秒
messageCode
String 否 (兼容字段) 同 code
requestId
String
否
服务端返回的客户端请求唯一编号，用于服务端排错，由服务端决定是否启用。
否
服务端返回的客户端请求唯一编号，用于服务端排错，由服务端决定是否启用。
说明
sucess, timestamp 始终必填，code, message 失败时必填，data 成功时必填
[遵守] API 不应直接返回 PO, 应定义对应的 VO, 避免返回敏感字段, 可使用 setter 和 getter 处理兼容问题
[遵守] API 返回类型的范型应明确且完整, 如: ResultBody<List<UserVO>>
状态码
0 条评论
下一页
