1 端点规范

API端点就是API的URI，例如：https://api.example.com/users/me

优秀的端点设计的重要原则：

容易记忆，URI包含的功能一目了然。

1.1端点的基本设计规范

• 短小便于输入
• 人可以读懂
• 没有大小写混用
• 方便修改
• 不会暴露服务架构
• 规则统一

1.2 HTTP方法和端点

端点和HTTP可以被认定是操作对象和操作方法的关系。

URI ：HTTP  =  资源：动作 （*所以URI不能包含动词）

可以通过同一端点不同的HTTP的动作设计出多个API

 

1. GET：请求资源
2. POST：创建资源
3. PUT：修改资源所有数据
4. DELETE：删除资源
5. PATCH：修改资源部分数据
6. 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 注意事项

设计端点时应注意：

1. 注意使用名词的复数形式：表示资源的集合
2. 注意使用的单词：准确且语义正确的英文或英文缩写
3. 不要有空格及需要编码的字符：会让人不一目了然
4. 多个单词用连接符隔开：”/”，例如kafkaconnection应设计成/kafka/connections
5. search搜索功能（特殊）：违背RESTFul，但可以使用，如基础服务的搜索可设计为/bsearch/connections?name=test （Yahoo、Twitter都使用了search动词作为端点）

 

2 响应规范

1. 采用JSON格式返回响应数据
2. 避免无用的封装
3. 数据尽量扁平化，层级结构尽量少
4. 集合响应数据，使用对象去封装
5. 可以在响应里的添加额外数据，例如分页信息等
6. 响应字段采用蛇形结构。（参照：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的管理

1. 通过版本信息来管理API：主版本编号.次版本编号.补丁版本编号，例如：1.2.3（GitHub）

                 API没有发生变更，只是修复了bug，则增加补丁版本编号

                 API向下兼容的更变或废除某些特定功能，增加次版本编号

                 API向下不兼容时，增加主版本编号

     2. 尽量做到向下兼容，除非不得不

     3. 停止API的使用：返回410-GONE，文档中注明API使用期限等

     4. API编排

5 API安全

可采用oauth2.0对接口进行安全管理