API 规范
2022-07-20 14:40:50 1 举报
AI智能生成
API接口规范
作者其他创作
大纲/内容
格式: https://{host}:{port}/{application}/api/{version}/{resources}
字母一律小写,使用横线 '-' 作为连字符,不允许使用下划线正确示例: /api/v1.0/automation/sap-jobs
使用/来表示资源的层级关系
资源统一使用复数形式
清晰易懂,没有歧义,并避免过多的路径嵌套
不应以 \"/\" 结尾
使用-来分隔一些单词
长度应控制在 2083 个字符以内
不应包含资源的扩展名(以 Content-Type 协商的数据格式为准)错误示例: GET /automation/api/v1.0/servers.json
URI 可以使用查询字段作为过滤条件,并在 API 文档中明确说明每个字段的含义、格式、使用场景等。正确示例:GET /automation/api/v1.0/servers?page=1&size=20
全小写,使用横线'-'作为连字符
只有post 请求中,uri 才可以使用
不以\"/\" 结尾
总结
URI
不可用 GET 来创建、删除、修改资源等对持久化资源/服务器状态有副作用的场景
通常使用 GET 来查询资源; 仅当一些请求体较大较复杂的情况需使用 POST
GET
既然PUT和POST操作都是向服务器端发送数据的,那么两者有什么区别呢。POST主要作用在一个集合资源之上的(url),而PUT主要作用在一个具体资源之上的(url/xxx),通俗一下讲就是,如URL可以在客户端确定,那么可使用PUT,否则用POST。
POST
PATCH
PUT
DELETE
OPTIONS
HEAD
只允许使用的动词
method
content-type
Accept
Authorization
请求头
服务端返回数据应使用统一的外层结构
不可强制要求客户端传送空字段
避免冗余数据的来回传递
时间戳是否存在时区的问题:时间戳的定义:从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数。从定义中发现,时间戳规定了地点(相当于时区)和起始时间,所以不存在时区问题。
引申
数据交换有哪些要求
示例
page
每页大小
size 无效时可使用默认值
size
值格式为: \
sort
分页及带排序查询api如何写
请求体
响应头
Boolean是标识是否调用成功。如果正确使用HTTP返回码,该字段其实不需要。但为了前端调用的便利性,目前该字段依然强制要求。
success
String是 (失败时)成功时,补充性信息出错时,服务端返回的错误编码(不同于 HTTP 状态码)。
code
message
Object / Array是 (成功时)服务端成功响应请求后,返回给客户端的数据。以 JSON 对象或对象列表方式返回。针对每一个API,需要具体定义。定义规范同请求体数据结构。
data
timestamp
String 否 (兼容字段) 同 code
messageCode
String否服务端返回的客户端请求唯一编号,用于服务端排错,由服务端决定是否启用。
requestId
结构
说明
响应体
状态码
API规范
API 规范
0 条评论
回复 删除
下一页