API设计规范

爱被打了一巴掌 2022-03-16 09:12 312阅读 0赞

# **1 端点规范** #

API端点就是API的URI，例如：[https://api.example.com/users/me][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字开头状态码：成功**

** 3字开头状态码：添加必要的处理**

3开头的状态码常被用于重定向操作。当客户端访问URI，服务器返回3开头的状态码时，响应消息里会返回名为Location的响应消息首部，其中包含了新的URI地址。

** 4字开头状态码：客户端请求发生问题**

<table style="width:426.1pt;"> 
 <tbody> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 状态码 </td> 
 <td style="vertical-align:top;width:121.8pt;"> 名称 </td> 
 <td style="vertical-align:top;width:162.3pt;"> 说明 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 400 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Bad Request </td> 
 <td style="vertical-align:top;width:162.3pt;"> 请求不正确 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 401 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Unauthorized </td> 
 <td style="vertical-align:top;width:162.3pt;"> 需要认证 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 403 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Forbidden </td> 
 <td style="vertical-align:top;width:162.3pt;"> 禁止访问 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 404 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Not Found </td> 
 <td style="vertical-align:top;width:162.3pt;"> 没有找到指定资源 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 405 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Method Not Allowed </td> 
 <td style="vertical-align:top;width:162.3pt;"> HTTP请求类型出错 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 406 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Not Acceptable </td> 
 <td style="vertical-align:top;width:162.3pt;"> 不支持客户端指定的返回类型 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 408 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Request Timeout </td> 
 <td style="vertical-align:top;width:162.3pt;"> 服务端超时处理 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 409 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Confilct </td> 
 <td style="vertical-align:top;width:162.3pt;"> 资源冲突，例如邮箱地址被使用 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 410 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Gone </td> 
 <td style="vertical-align:top;width:162.3pt;"> 资源曾经存在现在已消失 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 413/414 </td> 
 <td style="vertical-align:top;width:121.8pt;"> RETL/RURL </td> 
 <td style="vertical-align:top;width:162.3pt;"> 请求体过长/请求URI过长 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 415 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Unsupported Media Type </td> 
 <td style="vertical-align:top;width:162.3pt;"> 不支持Content-Type里指定格式 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;width:142pt;"> 429 </td> 
 <td style="vertical-align:top;width:121.8pt;"> Too Many Request </td> 
 <td style="vertical-align:top;width:162.3pt;"> 限速：限制请求次数 </td> 
 </tr> 
 </tbody> 
</table>

** 5字开头状态码：服务器端发生问题**

# **4 API的管理** #

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

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

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

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

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

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

4. API编排

# 5 API安全 #

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

[https_api.example.com_users_me]: https://api.example.com/users/me