独家 | 提升API设计技能的22个最佳实践（附链接）-技术圈

作者：Mohammad Faisal
翻译：张一然
校对：和中华

本文约2000字，建议阅读7分钟
本文介绍了有关设计REST api的一些实用建议。

你是否曾对处处都像猜谜游戏一样的糟糕API感到生气, 好吧我就曾有过这种体会。在微服务架构下，我们必须对后端API设计遵循一致性。

今天我们将讨论一些要遵循的最佳实践, 我们会保证文章简短易读-请系好安全带！

首先，了解一些术语

任何的API设计都遵循面向资源设计（Resource Oriented Design）,它包含如下三个关键概念：

1. 资源: 资源就是一份数据,比如,一个用户

2. 集合: 一组资源叫集合,比如一个用户列表

3. URL:标识资源或集合的地址, 比如 /user

1. 对URLs使用kebab-case命名法

例如,如果你想获得订单列表

差的示例：

/systemOrders 或者 /system_orders

好的示例：

/system-orders

2. 对参数使用驼峰命名法

例如, 如果你想从一个特定商店获得产品

差的示例：

/system-orders/{order_id} 或者 /system-orders/{OrderId}

好的示例：

/system-orders/{orderId}

3. 对集合使用复数命名法

如果你想获得系统中的所有用户

差的示例：

GET /user 或者 GET /User

好的示例：

GET /users

4. URL以集合开头以标识符结尾

如果你想要保证概念的单一和一致性

差的示例：

GET /shops/:shopId/category/:categoryId/price

这种写法很糟糕,因为该URL指向的是一个属性而非资源。

好的示例：

GET /shops/:shopId/ 或者 GET /category/:categoryId

5. 资源URL中不要出现动词

不要在URL中使用动词表达你的目的, 应该用适当的HTTP方法描述一个操作

差的示例：

POST /updateuser/{userId} or GET /getusers

好的示例：

PUT /user{userId}

6. 在非资源URL中使用动词

如果您有一个仅返回单个操作的端点，您可以使用动词。例如，如果您想向用户重新发送警报。

好的例子：

POST /alerts/245743/resend

记住这些操作不是增删改查操作, 而是在我们的系统里用来完成特定任务的功能

7. 对JSON属性使用驼峰命名

如果在你构建的系统中,你的请求体或者响应是JSON, 那么属性名应该使用驼峰命名法

差的示例：

{user_name: "Mohammad Faisal"user_id: "1"}

好的示例：

{userName: "Mohammad Faisal"userId: "1"}

8. 监控

RESTful HTTP 服务必须实现 /health 和 /version 以及 /metrics端点。他们将提供以下信息。

/health

使用 200 OK 状态代码响应对 /health 的请求。

/version

用版本号响应/version的请求。

/metrics

此端点将提供各种指标，例如平均响应时间。

此外也强烈推荐/debug 和 /status 端点。

9. 不要使用 table_name 作为资源名称

不要使用tabel_name命名你的资源, 从长远来看这种偷懒是有害的

差的示例：

product_order

好的示例：

product-orders

因为这会无意间暴露底层架构。

10. 使用API设计工具

有很多好的 API 设计工具可以用来制作好的文档，例如

API Blueprint
Swagger

对你的API用户来说，一份优秀详细的文档会带来非常棒的用户体验

11. 使用简单序数作为版本

始终对 API 进行版本控制并将向左移动，以使其具有最高的范围。版本号应为 v1、v2 等。

好的示例：

http://api.domain.com/v1/shops/3/products

始终对API使用版本控制的原因是如果你的API被外部实体使用, 更改端点会破坏其功能。

12. 在您的响应中包括资源总数

如果 API 返回一个对象列表，在响应中经常包含资源总数。您可以为此使用 total 属性。

差的示例：

{users: [ ...]}

好的示例：

{  users: [      ...  ],  total: 34}

13. 接受限制和偏移参数

在GET操作中始终接受limit和offset参数。

好的示例：

GET /shops?offset=5&limit=5

这是因为前端需要分页。

14. 获取字段查询参数

考虑到要返回的数据量, 添加 fields 参数仅公开 API 中的必需字段。

例子：

仅返回商店的姓名，地址，和联系方式

GET /shops?fields=id,name,address,contact

在有些例子中它也有助于减少响应的大小。

15. 不要在 URL 中传递身份验证令牌

这是一个非常糟糕的例子, 因为URLs经常被日志记录, 因此身份验证令牌也会被不必要地记录上

差的例子：

GET /shops/123?token=some_kind_of_authenticaiton_token

好的例子：

将它们与标头一起传递：

Authorization: Bearer xxxxxx, Extra yyyyy

同时，身份验证令牌时效性应该很短。

16. 验证内容的类型

服务器不应内容类型。例如，如果您接受 application/x-www-form-urlencoded，那么攻击者可以创建一个表单并触发一个简单的 POST 请求。

因此，要经常验证content-type ，如果您想使用默认类型，请使用content-type: application/json

17. 对增删查改功能使用HTTP方法

HTTP方法用于解释增删查改功能

GET：检索资源的表示。
POST：创建新资源和子资源。
PUT：更新现有资源。
PATCH：更新现有资源。它只更新提供的字段，其他字段不理会
DELETE：删除现有资源。

18. 将 URL 中的关系用于嵌套资源

一些实际例子是：

GET /shops/2/products ：从商店 2 获取所有产品的列表。
GET /shops/2/products/31：获取店铺2中商品31的详细信息
DELETE /shops/2/products/31 ，应该删除店铺 2 中的产品 31。
PUT /shops/2/products/31 ，应该更新产品 31 的信息，只在资源 URL 上使用 PUT，而不是集合URL。
POST /shops ，应该创建一个新商店并返回创建的新商店的详细信息。在集合 URL 上使用 POST。

19. CORS

支持所有面向公众的 API 的 CORS（跨源资源共享）标头。

考虑支持 CORS 允许的“*”来源，并通过有效的 OAuth 令牌强制执行授权。

避免将用户凭证与来源验证结合使用。

20. 安全性

强制HTTPS（TLS 加密)跨所有端点、资源和服务。

对所有回调 URL强制执行并要求 HTTPS, 推送通知端点和 Webhook 。

21. 错误

当客户端向服务器发出无效/不正确的请求，或者传输了无效/不正确的数据，而服务器拒绝该请求时，就会报错，具体来说是服务器错误。

例如无效的身份验证凭据、错误的参数、未知的版本 ID 等。

由于一个或多个服务错误而拒绝客户端请求时，请务必返回 4xx HTTP 错误代码。
考虑处理所有属性，然后在单个响应中返回多个验证问题。

22. 黄金法则

如果您对 API 格式化决策有任何疑问，这些黄金法则可以帮助指导我们做出正确的决定。

扁平比嵌套好。
简单胜于复杂。
字符串比数字好。
一致性优于定制。

这就是本文全部内容——恭喜你看到最后！我希望你从中学到一些东西。

祝你今天愉快！

原文链接：

https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9

编辑：王菁

校对：龚力

译者简介

张一然，哥本哈根大学计算机系硕士毕业, 研究方向为图像补全。现从事自然语言处理工作。感兴趣方向为计算机视觉和自然语言处理，喜欢看书旅游。

翻译组招募信息

工作内容：需要一颗细致的心，将选取好的外文文章翻译成流畅的中文。如果你是数据科学/统计学/计算机类的留学生，或在海外从事相关工作，或对自己外语水平有信心的朋友欢迎加入翻译小组。

你能得到：定期的翻译培训提高志愿者的翻译水平，提高对于数据科学前沿的认知，海外的朋友可以和国内技术应用发展保持联系，THU数据派产学研的背景为志愿者带来好的发展机遇。

其他福利：来自于名企的数据科学工作者，北大清华以及海外等名校学生他们都将成为你在翻译小组的伙伴。

点击文末“阅读原文”加入数据派团队~

转载须知

如需转载，请在开篇显著位置注明作者和出处（转自：数据派ID：DatapiTHU），并在文章结尾放置数据派醒目二维码。有原创标识文章，请发送【文章名称-待授权公众号名称及ID】至联系邮箱，申请白名单授权并按要求编辑。

发布后请将链接反馈至联系邮箱（见下方）。未经许可的转载以及改编者，我们将依法追究其法律责任。

点击“阅读原文”拥抱组织