RESTful API 设计最佳实践
5星 · 超过95%的资源 需积分: 49 147 浏览量
2022-03-20
12:31:40
上传
评论 1
收藏 45KB DOCX 举报 
RESTful API 设计最佳实践
数据模型已经稳定，接下来你可能需要为 web（网站）应用创建一个公开的 API（应用程序编程接口）。需要认识到这样一个问
题：一旦 API 发布后，就很难对它做很大的改动并且保持像先前一样的正确性。现在，网络上有很多关于 API 设计的思路。但是在
全部案例中没有一种被广泛采纳的标准，有很多的选择：你接受什么样的格式？如何认证？API 应该被版本化吗？
在为 SupportFu（一个轻量级的 Zendesk 替换实现）设计 API 时，对于这些问题我尽量得出一些务实的答案。我的目标是设
计这样一个 API，它容易使用和采纳，足够灵活去为我们用户接口去埋单。•
API 的关键要求
许多网上能找到的 API 设计观点都是些学术讨论，这些讨论是关于模糊标准的主观解释，而不是关于在现实世界中具有意义的
事。本文中我的目标是，描述一下为当今的 web 应用而设计的实用的 API 的最佳实践。如果感觉不对，我不会去尝试满足某个标准 。
为了帮助进行决策，我已经写下了 API 必须力争满足的一些要求:
它应当在需要的地方使用•web 标准
它应当对开发者友好并且便于在浏览器地址栏中浏览和探索
它应当是简单、直观和一致的，使它用起来方便和舒适
它应当提供足够的灵活性来增强大多数的•SupportFu用户界面
它应当是高效的，同时要维持和其他需求之间的平衡
一个•API 是一个开发者的•UI - 就像其他任何•UI 一样, 确保用户体验被认真的考虑过是很重要的!
使用•RESTful URLs and actions
如 果 有 一 样 东 西 获 得 广 泛 认 可 的 话 ，那就是 • RESTful 原则。Roy Felding在 他 论 文 •network based software
architectures的•第五章•中首次介绍了这些原则。
这些 REST 的关键原则与将你的•API 分割成逻辑资源紧密相关。使用 HTTP 请求控制这些资源，其中，这些方法（GET,
POST, PUT, PATCH, DELETE）具有特殊含义。
一旦定义好了资源, 需要确定什么样的•actions应用它们，这些•actions 怎么映射到你的•API 上。RESTful 原则提供
了•HTTP methods 映射作为策略来处理•CRUDactions，如下：
GET /tickets- 获取•tickets 列表
GET /tickets/12- 获取一个单独的•ticket
POST /tickets- 创建一个新的•ticket
PUT /tickets/12- 更新•ticket #12
PATCH /tickets/12- 部分更新•ticket #12
DELETE /tickets/12- 删除•ticket #12
REST 非常棒的是，利用现有的•HTTP 方法在单个的•/tickets 接入点上实现了显著的功能。没有什么方法命名约定需要去遵
循，URL 结构是整洁干净的。•REST 太棒了!
接入点的名称应该选择单数还是复数呢？keep-it-simple 原则可以在此应用。虽然你内在的语法知识会告诉你用复数形式描
述单一资源实例是错误的，但实用主义的答案是保持 URL 格式一致并且始终使用复数形式。不用处理各种奇形怪状的复数形式（比
如 person/people，goose/geese）可以让 API 消费者的生活更加美好，也让 API 提供者更容易实现 API（因为大多数现代框架
天然地将/tickets 和/tickets/12 放在同一个控制器下处理）。
但是你该如何处理（资源的）关系呢？如果关系依托于另外一个资源，Restful 原则提供了很好的指导原则。让我们来看一个
例子。SupportFu 的一个 ticket 包含许多消息（message）。这些消息逻辑上与/tickets 接入点的映射关系如下：
GET /tickets/12/messages - 获取 ticket #12 下的消息列表
GET /tickets/12/messages/5 - 获取 ticket #12 下的编号为 5 的消息
POST /tickets/12/messages - 为 ticket #12 创建一个新消息
评论10
最新资源