
云原生 API 网关 APISIX 入门教程
英文 | https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9
翻译 | 小爱你是否曾经对可怕的API感到沮丧,而这一切都是猜谜游戏?好吧,我有。在这个微服务世界中,必须为后端API设计一致的接口。今天,我们将讨论API的一些最佳实践。
首先,需要了解一些术语
任何API设计都需要遵循一个称为“Resource Oriented Design ”的概念,它包含三个关键概念
不好做法:
/systemOrders or /system_orders
好的做法:
/ system-orders
例如,如果你想从特定商店获取产品。
不好做法:
/system-orders/{order_id} or /system-orders/{OrderId}
好的做法:
/system-orders/{orderId}
如果要获取系统的所有用户。
不好做法:
GET /user or GET /User
好的做法:
GET /users
如果要保持概念单一和一致。
不好做法:
GET /shops/:shopId/category/:categoryId/price
好的做法:
GET /shops/:shopId/ or GET /category/:categoryId
请勿使用动词在URL中表达你的意图。而是使用正确的HTTP方法来描述操作。
不好做法:
POST /updateuser/{userId} or GET /getusers
好的做法:
PUT /user/{userId
你有一个端点,该端点只返回一个操作。在这种情况下,你可以使用动态。例如,如果你想将警报重新发送给用户。
不好做法:
POST /alerts/245743/resend
请记住,这些不是我们的CRUD操作。相反,这些被认为是在我们的系统中起特定作用的功能。
如果要构建请求主体或响应为JSON的系统,则属性名称应位于camelCase
不好做法:
{
user_name: "Mohammad Faisal"
user_id: "1"
}
好的做法:
{
userName: "Mohammad Faisal"
userId: "1"
}
RESTful HTTP服务必须实现/health和/version和/metrics API端点。他们将提供以下信息。
/health
/health用200 OK状态码响应请求。
/version
/version用版本号响应请求。
/metrics
该端点将提供各种指标,例如平均响应时间。
/debug 并且 /status也强烈推荐端点。
不要只使用表名作为资源名。从长远来看,这种懒惰可能是有害的。
不好做法:product_order
好的做法:product-orders
这是因为公开底层体系结构不是你的目的。
有许多优秀的API设计工具可用于提供良好的文档,例如:
拥有良好而详尽的文档可以为n的API使用者带来出色的用户体验。
始终对API使用版本控制,并一直将其向左移动,以使其具有最大的作用域。版本号应为v1,v2等等。
好的:
http://api.domain.com/v1/shops/3/products
始终在API中使用版本控制,因为如果外部实体正在使用该API,则更改端点可能会破坏其功能。
如果API返回了一个对象列表,则在响应中始终包含资源总数。您可以total为此使用属性。
不好做法:
{
users: [
...
]
}
好的做法:
{
users: [
...
],
total: 34
}
在操作中始终接受limit和offset参数GET。
好的:
GET /shops?offset=5&limit=5
这是因为在前端进行分页是必要的。
还应考虑返回的数据量。添加fields参数以仅公开API中的必填字段。
例子:
只返回商店的名称,地址和联系方式。
GET /shops?fields=id,name,address,contact
在某些情况下,它还有助于减小响应大小。
这是非常不好的做法,因为通常会记录URL,并且还会不必要地记录身份验证令牌。
不好做法:
GET / shops / 123?token = some_kind_of_authenticaiton_token
好的:相反,将其传递给标头:
Authorization: Bearer xxxxxx, Extra yyyyy
另外,授权令牌应该是短命的。
服务器不应采用内容类型。例如,如果您接受,application/x-www-form-urlencoded则攻击者可以创建表单并触发简单的POST请求。
因此,请始终验证content-type,如果您想使用默认的一种用法content-type: applicaiton/json
GET:检索资源的表示形式。
POST:创建新的资源和子资源。
PUT:更新现有资源。
PATCH:更新现有资源。它仅更新所提供的字段,而其他字段不予处理
DELETE:删除现有资源。
确实为所有面向公众的API支持CORS(跨源资源共享)标头。
考虑支持CORS允许的来源“ *”,并通过有效的OAuth令牌强制执行授权。
避免将用户凭据与原始验证结合在一起。
跨所有端点,资源和服务强制实施HTTPS(TLS加密)。
对所有回调URL,推送通知终结点和webhooks强制实施并要求HTTPS。
当客户端向服务提出无效或不正确的请求或向服务传递无效或不正确的数据时,就会发生错误,或更具体地说是服务错误。
示例包括无效的身份验证凭据,不正确的参数,未知的版本ID等。
如果您对API格式的决定有疑问,这些黄金规则可以帮助指导我们做出正确的决定。
就是这样-恭喜您已经做到了!我希望你学到了一两件事。
祝你编程愉快!
本文章转载微信公众号@web前端开发