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

设计优美的 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/#/home

其余

旧的 URI
http://api.example.com/users/123
新的 URI
http://newapi.example.com/users/123

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

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

引入版本号 -v2
http://api.tumblr.com/v2/blog/good.tumblr.com/info
老版本
http://www.davidslog.com/api/read

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

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

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

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

参考：
7 Rules for REST API URI Design