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

翻译 | 小爱

首先，需要了解一些术语

• 资源：资源是一条数据，例如User。
• 集合：一组资源称为集合，示例：用户列表
• URL：标识资源或集合的位置。例子：/user

不好做法：

/systemOrders or /system_orders

好的做法：

/ system-orders

2、使用camelCase作为参数

例如，如果你想从特定商店获取产品。

不好做法：

/system-orders/{order_id} or /system-orders/{OrderId}

好的做法：

/system-orders/{orderId}

3、指向集合的复数名称

如果要获取系统的所有用户。

不好做法：

GET /user or GET /User

好的做法：

GET /users

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

如果要保持概念单一和一致。

不好做法：

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

好的做法：

GET /shops/:shopId/ or GET /category/:categoryId

5、避免动词进入你的资源URL

请勿使用动词在URL中表达你的意图。而是使用正确的HTTP方法来描述操作。

不好做法：

POST /updateuser/{userId} or GET /getusers

好的做法：

PUT /user/{userId

6、对非资源URL使用动态

你有一个端点，该端点只返回一个操作。在这种情况下，你可以使用动态。例如，如果你想将警报重新发送给用户。

不好做法：

POST /alerts/245743/resend

请记住，这些不是我们的CRUD操作。相反，这些被认为是在我们的系统中起特定作用的功能。

7、使用camelCase作为JSON属性

如果要构建请求主体或响应为JSON的系统，则属性名称应位于camelCase

不好做法：

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

好的做法：

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

8、监控

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

/health

/health用200 OK状态码响应请求。

/version

/version用版本号响应请求。

/metrics

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

/debug 并且 /status也强烈推荐端点。

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

不要只使用表名作为资源名。从长远来看，这种懒惰可能是有害的。

不好做法：product_order

好的做法：product-orders

这是因为公开底层体系结构不是你的目的。

10、使用API设计工具

有许多优秀的API设计工具可用于提供良好的文档，例如：

• API蓝图：https://apiblueprint.org/

• 昂首阔步：https://swagger.io/

拥有良好而详尽的文档可以为n的API使用者带来出色的用户体验。

11、使用简单序号作为版本ni

始终对API使用版本控制，并一直将其向左移动，以使其具有最大的作用域。版本号应为v1，v2等等。

好的：

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

始终在API中使用版本控制，因为如果外部实体正在使用该API，则更改端点可能会破坏其功能。

12、在响应中包括资源总数

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

不好做法：

{  users: [      ...  ]}

好的做法：

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

13、接受极限和偏移参数

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

好的：

GET /shops?offset=5&limit=5

这是因为在前端进行分页是必要的。

14、取字段查询参数

还应考虑返回的数据量。添加fields参数以仅公开API中的必填字段。

例子：

只返回商店的名称，地址和联系方式。

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

在某些情况下，它还有助于减小响应大小。

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

这是非常不好的做法，因为通常会记录URL，并且还会不必要地记录身份验证令牌。

不好做法：

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: applicaiton/json

17、对CRUD功能使用HTTP方法

HTTP方法用于解释CRUD功能。

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，而不是集合）上的信息。

• POST /shops，应创建一个新商店并返回创建的新商店的详细信息。在collection-URL上使用POST。

19、 CORS

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

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

避免将用户凭据与原始验证结合在一起。

20、安全性

跨所有端点，资源和服务强制实施HTTPS（TLS加密）。

对所有回调URL，推送通知终结点和webhooks强制实施并要求HTTPS。

21、错误

当客户端向服务提出无效或不正确的请求或向服务传递无效或不正确的数据时，就会发生错误，或更具体地说是服务错误。

示例包括无效的身份验证凭据，不正确的参数，未知的版本ID等。

• 4xx当由于一个或多个服务错误而拒绝客户端请求时，请返回HTTP错误代码。

• 考虑处理所有属性，然后在单个响应中返回多个验证问题。

22、黄金法则

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

• 扁平比嵌套更好。

• 简单胜于复杂。

• 字符串胜于数字。

• 一致性比自定义更好。

就是这样-恭喜您已经做到了！我希望你学到了一两件事。

祝你编程愉快！

学习更多技能

请点击下方公众号