1 端点规范
API端点就是API的URI，例如：https://api.example.com/users/me
优秀的端点设计的重要原则：
容易记忆，URI包含的功能一目了然。
1.1端点的基本设计规范
- 短小便于输入
- 人可以读懂
- 没有大小写混用
- 方便修改
- 不会暴露服务架构
- 规则统一
1.2 HTTP方法和端点
端点和HTTP可以被认定是操作对象和操作方法的关系。
URI ：HTTP = 资源：动作 （*所以URI不能包含动词）
可以通过同一端点不同的HTTP的动作设计出多个API
- GET：请求资源
- POST：创建资源
- PUT：修改资源所有数据
- DELETE：删除资源
- PATCH：修改资源部分数据
- OPTION/HEAD：基本不用
1.3 分页规范
(参照：GitHub、Flickr)
per_page：一页条数
page ：第几页
例如：GET /kafka/connections?per_page=10&page=3
全量查询：page=all
例如：GET /kafka/connections?page=all
1.4 注意事项
设计端点时应注意：
- 注意使用名词的复数形式：表示资源的集合
- 注意使用的单词：准确且语义正确的英文或英文缩写
- 不要有空格及需要编码的字符：会让人不一目了然
- 多个单词用连接符隔开：”/”，例如kafkaconnection应设计成/kafka/connections
- search搜索功能（特殊）：违背RESTFul，但可以使用，如基础服务的搜索可设计为/bsearch/connections?name=test （Yahoo、Twitter都使用了search动词作为端点）
2 响应规范
- 采用JSON格式返回响应数据
- 避免无用的封装
- 数据尽量扁平化，层级结构尽量少
- 集合响应数据，使用对象去封装
- 可以在响应里的添加额外数据，例如分页信息等
- 响应字段采用蛇形结构。（参照：Twitter、Taobao、Facebook ：蛇形法参数）
例如：分页参数per_page=10待补充。
7.响应字段的名称（与VO一致，要求VO对象设计合理）
字段合理：1）使用多数API中表示相同含义的单词（正确的英文或英文缩写）
2）尽可能少的单词去表示
3）多单词采用蛇形法
4）注意单复数形式
5）性别：gender：male、female
6）注意大整数：JavaScript所有的数值都作为IEEE754标准的64比特浮点数处理，number支持的最大数为：2的53次方，所以处理大整数时就会出现误差。（可采用字符串方式返回大整数或新增一个String类型的JSON字段去展示大整数）
8. 响应数据没有必要如实反映DB的数据表结构。
9. 错误信息的响应：采用对象法封装，error字段作为对象，其参数包括：code（错误码）、message（错误信息）、或者加上document_url（如何处理错误的document的API端点）等
10. 局部响应
11. 发生错误防止返回HTML。客户端请求API服务端API时，产生404或500等异常时，不应直接返回HTML，API设计时要对这一类异常有统一的JSON返回形式的处理。
12.维护API。
1）API服务器停止对外服务，应有相应的状态码503告知用户当前服务已经停止。
2）使用Retry-After这一HTTP首部告知用户维护的结束时间（HTTP1.1协议规范）
3 HTTP状态码
正确的使用状态码：有些API无论如何访问（产生500异常），都返回200，只是把错误信息放在响应信息里，这样是不符合HTTP协议的。
2字开头状态码：成功
| 状态码 |
名称 |
说明 |
| 200 |
OK |
请求成功，用于PUT或PATCH请求 |
| 201 |
Created |
资源被成功创建，用于POST请求 |
| 202 |
Accepted |
请求成功，正在处理 |
| 204 |
No Content |
空内容，用于DELETE请求 |
3字开头状态码：添加必要的处理
3开头的状态码常被用于重定向操作。当客户端访问URI，服务器返回3开头的状态码时，响应消息里会返回名为Location的响应消息首部，其中包含了新的URI地址。
4字开头状态码：客户端请求发生问题
| 状态码 |
名称 |
说明 |
| 400 |
Bad Request |
请求不正确 |
| 401 |
Unauthorized |
需要认证 |
| 403 |
Forbidden |
禁止访问 |
| 404 |
Not Found |
没有找到指定资源 |
| 405 |
Method Not Allowed |
HTTP请求类型出错 |
| 406 |
Not Acceptable |
不支持客户端指定的返回类型 |
| 408 |
Request Timeout |
服务端超时处理 |
| 409 |
Confilct |
资源冲突，例如邮箱地址被使用 |
| 410 |
Gone |
资源曾经存在现在已消失 |
| 413/414 |
RETL/RURL |
请求体过长/请求URI过长 |
| 415 |
Unsupported Media Type |
不支持Content-Type里指定格式 |
| 429 |
Too Many Request |
限速：限制请求次数 |
5字开头状态码：服务器端发生问题
| 状态码 |
名称 |
说明 |
| 500 |
Internal Server Error |
服务端发生错误 |
| 503 |
Service Unavailable |
服务器端不可用或暂停状态 |
4 API的管理
- 通过版本信息来管理API：主版本编号.次版本编号.补丁版本编号，例如：1.2.3（GitHub）
API没有发生变更，只是修复了bug，则增加补丁版本编号
API向下兼容的更变或废除某些特定功能，增加次版本编号
API向下不兼容时，增加主版本编号
2. 尽量做到向下兼容，除非不得不
3. 停止API的使用：返回410-GONE，文档中注明API使用期限等
4. API编排
5 API安全
可采用oauth2.0对接口进行安全管理
到此这篇API设计规范的文章就介绍到这了,更多相关内容请继续浏览下面的相关推荐文章，希望大家都能在编程的领域有一番成就！版权声明：
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！
转载请注明出处，原文链接：https://www.xkablog.com/hd-api/4401.html