RESTful API 最佳实践

目录

路径名称避免动词

URI 使用复数形式

子资源路径

善用 HTTP 状态码

版本管理

---

强调组件间的 统一接口 是 REST 架构风格与其他基于网络的风格区分开来的核心特征，基于此特征，本文梳理了RSETful 最佳实践，以帮助更好的设计 API。

路径名称避免动词

使用 HTTP 方法来表达资源操作行为，而不是将行为动词定义到路径中。

# Good curl -X GET http://httpbin.org/orders # Bad curl -X GET "http://httpbin.org/getOrders"

• GET 获取指定 URI 的资源信息

# 代表获取当前系统的所有订单信息 curl -X GET http://httpbin.org/orders # 代表获取订单编号为 1 的订单详情信息 curl -X GET http://httpbin.org/orders/1

• POST 通过指定的 URI 创建资源

# 代表创建一个名称为 order 的资源 curl -X POST http://httpbin.org/orders \ -d '{"name": "awesome", region: "A"}' \

• PUT 创建或全量/部分替换指定 URI 上的资源

# 代表将 id 为 1 的 order 进行数据替换 curl -X PUT http://httpbin.org/orders/1 \ -d '{"name": "new awesome", region: "B"}' \

• PATCH 执行一个资源的部分更新------------低版本浏览器不支持，部分更新用PUT替代

# 代表将 id 为 1 的 order 中的 region 字段进行更改，其他数据保持不变 curl -X PATCH http://httpbin.org/orders/1 \ -d '{region: "B"}' \

• DELETE 通过指定的 URI 移除资源

# 代表将 id 为 1 的 order 删除 curl -X DELETE http://httpbin.org/orders/1

URI 使用复数形式

若使用单数的形式来表示获取某一类资源，例如：

curl -X GET "http://httpbin.org/order"

使用单数形式，会使用户产生该系统中只有一个 order 的困惑，用复数形式在逻辑上则顺畅很多。

curl -X GET "http://httpbin.org/orders"

子资源路径

子资源应归父资源所有，子资源名称应为名词复数，父资源的id应路径上体现，例如：

# 查询 某订单中的图片 curl -X GET "http://httpbin.org/orders/{id}/pictures"

示例 查询 订单编号为 1 的 order 中的图片：

# 查询 订单编号为 1 的 order 中的图片 curl -X GET "http://httpbin.org/orders/1/pictures"

善用 HTTP 状态码

HTTP 标准定义个状态码，大致可以分为以下几类：

状态码	含义
2xx	成功，操作被成功接收并处理
3xx	重定向，需要进一步的操作以完成请求
4xx	客户端错误，请求包含语法错误或无法完成请求
5xx	服务器错误，服务器在处理请求的过程中发生了错误

使用标准状态码，开发人员可以立即识别问题，可以减少发现不同类型错误的时间。

版本管理

随着业务需求的变更，已经上线的 API 大概率是要对应调整的。如果我们的 API 有第三方在使用，让每一个客户端根据我们 API 的变更而变更显然是不可能的，这个时候就要引入 API 版本管理概念了，既可以保证历史 API 正常使用，又可以迭代新的 API 以满足新的业务需求。

常见的版本控制手段有：

• 通过请求中路径来做版本控制

# 请求 v1 版本的API curl http://httpbin.org/v1/orders # 请求 v2 版本的API curl http://httpbin.org/v2/orders

• 通过 Query 参数来做版本控制

# 请求 v1 版本的API curl http://httpbin.org/orders?version=v1 # 请求 v2 版本的API curl http://httpbin.org/v2/orders?version=v2

• 通过 Header 来做版本控制

# 请求 v1 版本的API curl http://httpbin.org/orders -H "custom-version: v1" # 请求 v2 版本的API curl http://httpbin.org/orders -H "custom-version: v2"