良好的 API 设计指南RESTful API.docxVIP

良好的 API 设计指南-RESTful API 版本号 在 RESTful API 中，API 接口应当尽量兼容之前的版本。但是，在实际业务开发场景中，可能随着业务需求的不断迭代，现有的 API 接口无法支持旧版本的适配，此时假如强制升级服务端的 API 接口将导致客户端旧有功能消灭毛病。实际上，Web 端是部署在服务器，因而它可以很简约为了适配服务端的新的 API 接口进行版本升级，然而像 Android 端、IOS 端、PC 端等其他客户端是运转在用户的机器上，因而当前产品很难做到适配新的服务端的 API 接口，从而消灭功能毛病，这种情况下，用户必需升级产品到最新的版本才能正常使用。 为了处理这个版本不兼容问题，在设计 RESTful API 的一种有用的做法是使用版本号。一般情况下，我们会在 url 中保留版本号，并同时兼容多个版本。 【GET】 /v1/users/{user_id} // 版本 v1 的查询用户列表的 API 接口 【GET】 /v2/users/{user_id} // 版本 v2 的查询用户列表的 API 接口 现在，我们可以不转变版本 v1 的查询用户列表的 API 接口的情况下，新增版本 v2 的查询用户列表的 API 接口以满足新的业务需求，此时，客户端的产品的新功能将恳求新的服务端的 API 接口地址。虽然服务端会同时兼容多个版本，但是同时维护太多版本对于服务端而言是个不小的负担，由于服务端要维护多套代码。这种情况下，常见的做法不是维护全部的兼容版本，而是只维护最新的几个兼容版本，例如维护最新的三个兼容版本。在一段时间后，当绝大多数用户升级到较新的版本后，废弃一些使用量较少的服务端的老版本API 接口版本，并要求使用产品的格外旧的版本的用户强制升级。 留意的是，“不转变版本 v1 的查询用户列表的 API 接口”次要指的是对于客户端的调用者而言它看起来是没有转变。而实际上，假如业务变化太大，服务端的开发人员需要对旧版本的 API 接口使用适配器模式将恳求适配到新的API 接口上。 资源路径 RESTful API 的设计以资源为核心，每一个 URI 代表一种资源。因而，URI 不能包含动词，只能是名词。留意的是，描述词也是可以使用的，但是尽量少用。一般来说，不论资源是单个还是多个，API 的名词要以复数进行命名。此外，命名名词的时候，要使用小写、数字及下划线来区分多个单词。这样的设计是为了与 json 对象及属性的命名方案保持全都。例如，一个查询系统标签的接口可以进行如下设计。 【GET】 /v1/tags/{tag_id} 同时，资源的路径应当从根到子依次如下。 /{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property} 我们来看一个“添加用户的角色”的设计，其中“用户”是主资源，“角色”是子资源。 【POST】 /v1/users/{user_id}/roles/{role_id} // 添加用户的角色 有的时候，当一个资源变化难以使用标准的 RESTful API 来命名，可以考虑使用一些特殊的 actions 命名。 /{resources}/{resource_id}/actions/{action} 举个例子，“密码修改”这个接口的命名很难完全使用名词来构建路径，此时可以引入 action 命名。 【PUT】 /v1/users/{user_id}/password/actions/modify // 密码修改 恳求方式 可以通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。其中，GET 用于查询资源，POST 用于创建资源，PUT 用于更新服务端的资源的全部信息，PATCH 用于更新服务端的资源的部分信息，DELETE 用于删除服务端的资源。 这里，笔者使用“用户”的案例进行回顾通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。 【GET】 /users # 查询用户信息列表 【GET】 /users/1001 # 查看某个用户信息 【POST】 /users # 新建用户信息 【PUT】 /users/1001 # 更新用户信息(全部字段) 【PATCH】 /users/1001 # 更新用户信息(部分字段) 【DELETE】 /users/100