设计api考虑因素以及基本解决方法

古城微笑少年丶 2022-05-27 11:52 184阅读 0赞

#### 设计优美的 Web API ####

*  不用过分拘泥于 REST 一词。
 *  最大限度地减少 API 版本的更新频率，注意向下兼容性。
 *  在 URI 中嵌入 API 版本的主版本编号。
 *  停止提供 API 服务时不能立刻终止，至少需要继续公开 6 个月。
 *  最大程度地利用 **HTTP 协议规范**，最小程度地使用私有规范。
 *  使用合适的**状态码**。
 *  返回恰当的、尽可能通用的媒体类型。
 *  返回便于客户端执行恰当的缓存的信息。
 *  使用 **JSON** 或者和目的一致的数据格式。
 *  不要进行不必要的封装。
 *  响应数据尽可能使用扁平化结构。
 *  各个数据的名称应简洁易懂，并恰当地使用单复数。
 *  **错误格式应统一**，使客户端能够机械地理解错误的详细信息
 *  设计容易记忆、功能一目了然的端点。
 *  使用合适的 HTTP 方法。
 *  选择合适的英语单词，注意单词的单复数形式。
 *  使用 OAuth 2.0 进行认证。

--------------------

#### 具体操作 ####

您正在构建的一个或多个服务中的每个资源都至少有一个**唯一**标识它的URI。当这个URI合理并**充分描述**（简洁，层级清晰）资源时最好。

规则＃1：URI中不应包含结尾的正斜杠（/）

规则＃2：必须使用正斜杠分隔符（/）来表示分层关系

规则＃3：应使用连字符（ - ）来提高URI的可读性

规则\#4：不应在URI中使用下划线（\_）

规则＃5：在URI路径中应该首选小写字母

规则＃6：文件扩展名不应包含在URI中

规则\#7：要描述你的资源，使用具体的名字而不是动作动词。

规则\#8：端点名称应该是单数还是复数？复数

--------------------

#### 变化因素 ####

1.  我们的服务经常 **发生变化**，接口的 API 显然也随之改变。
2.  考虑是否会给 **第三方** 使用，变更 API 的设计是否给第三方设计带来影响。
3.  升级api，不会影响 **正在使用api** 的用户
4.  Web API 同 Web 站点一样使 用了 **HTTP 协议**，因此会面临同 Web 站点一样的安全问题，需考虑 API **特有的** 安全问题
5.  糟糕的 **Web API** 正体现了设计者或团队的 **糟糕**

--------------------

#### 版本信息管理 API ####

1- 可以同时提供 **多个版本** 的 API。旧版本使用以前接口，新版本使用跟新后接口

测试版本

> [http://localhost:4200/\#/newapi/home][http_localhost_4200_newapi_home]  
> [http://localhost:4200/\#/home][http_localhost_4200_home]

其余

> 旧的 URI  
> [http://api.example.com/users/123][http_api.example.com_users_123]  
> 新的 URI  
> [http://newapi.example.com/users/123][http_newapi.example.com_users_123]

2- URI 路径的 **开头**嵌入 **API 版本编号**

newapi 的设计不合理，因为 api 随时会更新

> 引入版本号 -v2  
> [http://api.tumblr.com/v2/blog/good.tumblr.com/info][http_api.tumblr.com_v2_blog_good.tumblr.com_info]  
> 老版本  
> [http://www.davidslog.com/api/read][http_www.davidslog.com_api_read]

3- 终止提供 API  
服务的**运营成本** ，**安全问题** ，**后端功能的更新**(如数据库 schema 的更改)

> 为了减轻维护负担，应尽可能地不去**频繁升级** API 版本

考虑到**安全隐患**(*如个人信息没有经过加密直接 被发送、能够获取他人的信息等*),考虑到成本问题，继续维护和支持多个版本的 API 是 **不现实**的，这种情况下就需要考虑选择适当时机去废除旧版本的 API。

> 因此，在终止 API 服务时，尤其是在终止那些已被广泛使用的 API 时，我们需  
> 要事先公布预计终止的时间等信息，以便用户在此之前采取应对措施。这项工程非 常复杂，但对 API 的公开及运营来说非常重要。

参考：  
[7 Rules for REST API URI Design][]

[http_localhost_4200_newapi_home]: http://localhost:4200/#/newapi/home
[http_localhost_4200_home]: http://localhost:4200/#/home
[http_api.example.com_users_123]: http://api.example.com/users/123
[http_newapi.example.com_users_123]: http://newapi.example.com/users/123
[http_api.tumblr.com_v2_blog_good.tumblr.com_info]: http://api.tumblr.com/v2/blog/good.tumblr.com/info
[http_www.davidslog.com_api_read]: http://www.davidslog.com/api/read
[7 Rules for REST API URI Design]: https://blog.restcase.com/7-rules-for-rest-api-uri-design/