我们都是架构师！
关注架构师(JiaGouX)，添加“星标”
获取每天技术干货，一起成为牛逼架构师
技术群请加若飞：1321113940 进架构师群
投稿、合作、版权等邮箱：admin@137x.com
其他
22条API设计的最佳实践
在这个微服务的世界里，后端API的一致性设计是必不可少的。
今天，我们将讨论一些可遵循的最佳实践。我们将保持简短和甜蜜——所以系好安全带，出发咯！
资源：资源是数据的一部分，例如：用户
集合：一组资源称为集合，例如：用户列表
URL：标识资源或集合的位置，例如：/user
不应该：
/systemOrders或/system_orders
/system-orders
不应该：
/system-orders/{order_id}
/system-orders/{OrderId}
/system-orders/{orderId}
不应该：
GET /user
GET /User
GET /users
不应该：
GET /shops/:shopId/category/:categoryId/price
应该：
GET /shops/:shopId/或GET /category/:categoryId
不应该：
POST /updateuser/{userId}
GET /getusers
PUT /user/{userId}
应该：
POST /alarm/245743/resend
不应该：
{
user_name: "Mohammad Faisal"
user_id: "1"
}
{
userName: "Mohammad Faisal"
userId: "1"
}
/health
用200 OK状态码响应对/health的请求。
/version
用版本号响应对/version的请求。
/metrics
这个端点将提供各种指标，如平均响应时间。
也强烈推荐使用/debug和/status端点。
不应该：
product_order
product-orders
API蓝图：https://apiblueprint.org/
Swagger：https://swagger.io/
拥有良好而详细的文档可以为API使用者带来良好的用户体验。
应该：http://api.domain.com/v1/shops/3/products
始终在API中使用版本控制，因为如果API被外部实体使用，更改端点可能会破坏它们的功能。
不应该：
{
users: [
...
]
}
{
users: [
...
],
total: 34
}
应该：
GET /shops?offset=5&limit=5
例子：
只返回商店的名称，地址和联系方式。
GET /shops?fields=id,name,address,contact
不应该：
GET /shops/123?token=some_kind_of_authenticaiton_token
Authorization: Bearer xxxxxx, Extra yyyyy
因此，始终验证内容类型，如果你想使用默认的内容类型，请使用：
content-type: application/json
GET：检索资源的表示形式。
POST：创建新的资源和子资源。
PUT：更新现有资源。
PATCH：更新现有资源，它只更新提供的字段，而不更新其他字段。
DELETE：删除已存在的资源。
GET /shops/2/products：从shop 2获取所有产品的列表。
GET /shops/2/products/31：获取产品31的详细信息，产品31属于shop 2。
DELETE /shops/2/products/31：应该删除产品31，它属于商店2。
PUT /shops/2/products/31：应该更新产品31的信息，只在resource-URL上使用PUT，而不是集合。
POST /shops：应该创建一个新的商店，并返回创建的新商店的详细信息。在集合url上使用POST。
考虑支持CORS允许的“*”来源，并通过有效的OAuth令牌强制授权。
避免将用户凭证与原始验证相结合。
强制并要求所有回调url、推送通知端点和webhooks使用HTTPS。
例子包括无效的身份验证凭证、不正确的参数、未知的版本id等。
当由于一个或多个服务错误而拒绝客户端请求时，一定要返回4xx HTTP错误代码。
考虑处理所有属性，然后在单个响应中返回多个验证问题。
扁平比嵌套好。
简单胜于复杂。
字符串比数字好。
一致性比定制更好。
就是这样——如果你已经走到了这一步，恭喜你！希望你学到了一些东西。
希望你度过美好的一天！
译者：Mr.lzc，软件工程师、DevOpsDays、HDZ深圳核心组织者，目前供职于华为，从事云计算工作，专注于K8s、微服务领域。
如喜欢本文，请点击右上角，把文章分享到朋友圈
如有想了解学习的技术点，请留言给若飞安排分享
·END·
相关阅读：
一张图看懂微服务架构路线 基于Spring Cloud的微服务架构分析 微服务等于Spring Cloud？了解微服务架构和框架 如何构建基于 DDD 领域驱动的微服务？ 微服务架构实施原理详解 微服务的简介和技术栈 微服务场景下的数据一致性解决方案 设计一个容错的微服务架构
译者：刘志超
来源：dockone.io/article/2434604
原文：https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9
版权申明：内容来源网络，仅供分享学习，版权归原创者所有。除非无法确认，我们都会标明作者及出处，如有侵权烦请告知，我们会立即删除并表示歉意。谢谢!