Designing Web APIs - 第二章上部 Request-Response APIs
前言
假想一下你的产品有新的需求,现有的API能否扩容?或者你想修改现有API,但是有很多生产环境在跑。为了省事省力省心,选择合适的API模型是十分重要的。
目前常见的API模型有:REST,RPC,GraphQL, WebHooks, and WebSockets.
REST
REST 全称是 Representational State Transfer,是对资源进行操作(CRUD,也就是常说的增删改查)。
REST 常见规则
- url 包含了资源,比如 /users。代表了目前的 api 是关于 users 的资源集合。
- 为了获取某一个特定的资源,直接在资源集合后面加上资源标识。例如 /users/123,这里我们可以认为该 api 是获取资源标识是 123 的user。
- 用名词代替动词。比如为了获取 123 这个 user,应该使用 /users/123,而不是 /getUserInfo/123
- 创建心的资源使用 POST;获取资源时使用 GET;对某个资源整体替换时使用 PUT;对某个资源进行局部更新时使用 PATCH;删除资源时使用 DELETE
- 使用标准的 HTTP status code 做返回码。
- 以 JSON 或 XML 形式返回。
REST 示例
操作 | Http 方法 | /users | /users/123 |
---|---|---|---|
Create | POST | 创建一个新用户 | 不适用于该 url |
Read | GET | 获取所有用户 | 获取用户 123 |
Update | PUT 或者 PATCH | 批量更新用户 | 更新用户 123 |
Delete | Delete | 删除所有用户 | 删除用户 123 |
REST 下那些非 CRUD 操作咋整?
一种通用的处理是把对应的操作动词加入到 url 中。比如 search,此时对应的 url 可以是 /search/code?q=....
RPC
RPC 的全称是 Remote Procedure Call(远程过程调用,即调用远程服务器上面的方法或者函数)。上面说到 REST 是关于资源进行操作,那么 RPC 就是关于函数或方法进行操作。
RPC 常见规则
- 终节点包含要操作的方法名称。
- 对于只读内容使用 GET 方法,其他情况下使用 POST 方法。
RPC 示例
方法 | 描述 |
---|---|
conversations.archive | 会话保存 |
conversations.close | 关闭会话 |
GraphQL
GraphQL 是一个查询语言。允许客户端定义需要的数据结构,然后服务端就会返回对应的数据结构。与 REST 和 RPC 不同,你不需要用不同的 HTTP 方法描述你的操作。
与 REST 与 RPC 相比的优势
- 与服务器建立更少的连接。RPC 通过一个简单的 Request 与服务器连接并查询与获取数据。
- 避免版本控制。在不影响现有查询的情况下可以添加新的字段。通过日志可以找出正在使用的字段。
- 负载更小。REST 与 RPC 的返回内容客户端无法控制,会返回一些用不到的数据。但是 GraphQL 不存在这种情况,客户端可以 精确指出需要的内容。
- 强类型。GraphQL 是强类型的,在开发时类型检查将帮助用户建立更可靠的客户端。
- 有内嵌浏览器的 IDE - GraphiQL,帮助用户开发测试 GraphQL。
总结。
内容 | REST | RPC | GraphQL |
---|---|---|---|
简介 | 对Resource进行CRUD | 对远程服务器上的 Actions 进行调用 | 一个查询语言,客户端决定返回结构 |
示例 | /user/123 | /user.get?id= | query ($id: String!) {user(login: $id) { name } } |
Http方法 | GET,POST,PUT,PATCH,DELETE | GET,POST | GET,POST |
使用场景 | 进行 CRUD 操作 | 远端服务器暴漏 actions | 需要提供灵活,优秀的查询 |