作者: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用户来说,一份优秀详细的文档会带来非常棒的用户体验
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方法用于解释增删查改功能
18. 将 URL 中的关系用于嵌套资源
一些实际例子是:
19. CORS
支持所有面向公众的 API 的 CORS(跨源资源共享)标头。
考虑支持 CORS 允许的“*”来源,并通过有效的 OAuth 令牌强制执行授权。
避免将用户凭证与来源验证结合使用。
20. 安全性
强制HTTPS(TLS 加密)跨所有端点、资源和服务。
对所有回调 URL强制执行并要求 HTTPS, 推送通知端点和 Webhook 。
21. 错误
当客户端向服务器发出无效/不正确的请求,或者传输了无效/不正确的数据,而服务器拒绝该请求时,就会报错,具体来说是服务器错误。
例如无效的身份验证凭据、错误的参数、未知的版本 ID 等。
22. 黄金法则
如果您对 API 格式化决策有任何疑问,这些黄金法则可以帮助指导我们做出正确的决定。
这就是本文全部内容——恭喜你看到最后!我希望你从中学到一些东西。
祝你今天愉快!
原文链接:
https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9
编辑:王菁
校对:龚力
译者简介
张一然,哥本哈根大学计算机系硕士毕业, 研究方向为图像补全。现从事自然语言处理工作。感兴趣方向为计算机视觉和自然语言处理,喜欢看书旅游。
翻译组招募信息
工作内容:需要一颗细致的心,将选取好的外文文章翻译成流畅的中文。如果你是数据科学/统计学/计算机类的留学生,或在海外从事相关工作,或对自己外语水平有信心的朋友欢迎加入翻译小组。
你能得到:定期的翻译培训提高志愿者的翻译水平,提高对于数据科学前沿的认知,海外的朋友可以和国内技术应用发展保持联系,THU数据派产学研的背景为志愿者带来好的发展机遇。
其他福利:来自于名企的数据科学工作者,北大清华以及海外等名校学生他们都将成为你在翻译小组的伙伴。
转载须知
如需转载,请在开篇显著位置注明作者和出处(转自:数据派ID:DatapiTHU),并在文章结尾放置数据派醒目二维码。有原创标识文章,请发送【文章名称-待授权公众号名称及ID】至联系邮箱,申请白名单授权并按要求编辑。
发布后请将链接反馈至联系邮箱(见下方)。未经许可的转载以及改编者,我们将依法追究其法律责任。