作者：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-orders2. 对参数使用驼峰命名法
例如, 如果你想从一个特定商店获得产品
差的示例：
/system-orders/{order_id} 或者 /system-orders/{OrderId}好的示例：
/system-orders/{orderId}3. 对集合使用复数命名法
如果你想获得系统中的所有用户
差的示例：
GET /user 或者 GET /User好的示例：
GET /users4. URL以集合开头以标识符结尾
如果你想要保证概念的单一和一致性
差的示例：
GET /shops/:shopId/category/:categoryId/price这种写法很糟糕,因为该URL指向的是一个属性而非资源。
好的示例：
GET /shops/:shopId/ 或者 GET /category/:categoryId5. 资源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】至联系邮箱，申请白名单授权并按要求编辑。
发布后请将链接反馈至联系邮箱（见下方）。未经许可的转载以及改编者，我们将依法追究其法律责任。