22条api设计的最佳实践-yb体育官方

曾经因为一个糟糕的api而感到沮丧吗？

在这个微服务的世界里，后端api的一致性设计是必不可少的。

今天，我们将讨论一些可遵循的最佳实践。我们将保持简短和甜蜜——所以系好安全带，出发咯！

首先介绍一些术语

任何api设计都遵循一种叫做“面向资源设计”的原则：

• 资源：资源是数据的一部分，例如：用户

• 集合：一组资源称为集合，例如：用户列表

• url：标识资源或集合的位置，例如：/user

1. 对url使用kebab-case（短横线小写隔开形式）

例如，如果你想要获得订单列表。

不应该：

/systemorders或/system_orders

应该：

/system-orders

2. 参数使用camelcase（驼峰形式）

例如，如果你想从一个特定的商店购买产品。

不应该：

/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

这很糟糕，因为它指向的是一个属性而不是资源。

应该：

get /shops/:shopid/或get /category/:categoryid

5. 让动词远离你的资源url

不要在url中使用动词来表达你的意图。相反，使用适当的http方法来描述操作。

不应该：

post /updateuser/{userid}

或：

get /getusers

应该：

put /user/{userid}

6. 对非资源url使用动词

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

应该：

post /alarm/245743/resend

请记住，这些不是我们的crud操作。相反，它们被认为是在我们的系统中执行特定工作的函数。

7. json属性使用camelcase驼峰形式

如果你正在构建一个请求体或响应体为json的系统，那么属性名应该使用驼峰大小写。

不应该：

{   user_name: "mohammad faisal"   user_id: "1"}

应该：

{   username: "mohammad faisal"   userid: "1"}

8. 监控

restful http服务必须实现/health和/version和/metricsapi端点。他们将提供以下信息。

/health

用200 ok状态码响应对/health的请求。

/version

用版本号响应对/version的请求。

/metrics

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

也强烈推荐使用/debug和/status端点。

9. 不要使用table_name作为资源名

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

不应该：

product_order

应该：

product-orders

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

10. 使用api设计工具

有许多好的api设计工具用于编写好的文档，例如：

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

• swagger：https://swagger.io/

拥有良好而详细的文档可以为api使用者带来良好的用户体验。

11. 使用简单序数作为版本

始终对api使用版本控制，并将其向左移动，使其具有最大的作用域。版本号应该是v1，v2等等。

应该：http://api.domain.com/v1/shops/3/products

始终在api中使用版本控制，因为如果api被外部实体使用，更改端点可能会破坏它们的功能。

12. 在你的响应体中包括总资源数

如果api返回一个对象列表，则响应中总是包含资源的总数。你可以为此使用total属性。

不应该：

{  users: [      ...  ]}

应该：

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

13. 接受limit和offset参数

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

应该：

get /shops?offset=5&limit=5

这是因为它对于前端的分页是必要的。

14. 获取字段查询参数

返回的数据量也应该考虑在内。添加一个fields参数，只公开api中必需的字段。

例子：

只返回商店的名称，地址和亚博平台app下载的联系方式。

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

17. 对crud函数使用http方法

http方法用于解释crud功能。

get：检索资源的表示形式。

post：创建新的资源和子资源。

put：更新现有资源。

patch：更新现有资源，它只更新提供的字段，而不更新其他字段。

delete：删除已存在的资源。

18. 在嵌套资源的url中使用关系

以下是一些实际例子：

• 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。

19. cors（跨源资源共享）

一定要为所有面向公共的api支持cors（跨源资源共享）头部。

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

避免将用户凭证与原始验证相结合。

20. 安全

在所有端点、资源和服务上实施https（tls加密）。

强制并要求所有回调url、推送通知端点和webhooks使用https。

21. 错误

当客户端向服务发出无效或不正确的请求，或向服务传递无效或不正确的数据，而服务拒绝该请求时，就会出现错误，或者更具体地说，出现服务错误。

例子包括无效的身份验证凭证、不正确的参数、未知的版本id等。

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

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

22. 黄金法则

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

• 扁平比嵌套好。

• 简单胜于复杂。

• 字符串比数字好。

• 一致性比定制更好。

就是这样——如果你已经走到了这一步，恭喜你！希望你学到了一些东西。

希望你度过美好的一天！

译者：mr.lzc，软件工程师、devopsdays、hdz深圳核心组织者，目前供职于华为，从事云计算工作，专注于k8s、微服务领域。