大家好，关于22个优秀实践助你API设计能力更上一层楼-api 设计很多朋友都还不太明白，今天小编就来为大家分享关于的知识，希望对各位有所帮助！

曾经因为一个糟糕的API而感到沮丧吗?

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

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

[[424906]]

首先介绍一些术语

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

1. 资源：资源是数据的一部分，例如：用户
2. 集合：一组资源称为集合，例如：用户列表
3. URL：标识资源或集合的位置，例如：/用户

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蓝图
• Swagger

拥有良好而详细的文档可以为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中必需的字段。

例子:

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(跨源资源共享)头部。

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

20.安全

在所有端点、资源和服务上实施HTTPS (tls加密)。

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

21. 错误

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

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

• 当由于一个或多个服务错误而拒绝客户端请求时，一定要返回4xx HTTP错误代码。
• 考虑处理所有属性，然后在单个响应中返回多个验证问题。

22. 黄金法则

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

• 扁平比嵌套好。
• 简单胜于复杂。
• 字符串比数字好。
• 一致性比定制更好。

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

希望你度过美好的一天!

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

 

用户评论

青山暮雪

API 设计真的很重要啊，不知道这22个实践能帮我什么，看起来很期待。

    有14位网友表示赞同！

情深至命

刚开始接触API 设计，感觉很迷茫，这篇文章也许就能给我一些帮助了。

    有8位网友表示赞同！

艺菲

我一直想提升我的API设计能力，看看这些实践是否能让我有所突破。

    有10位网友表示赞同！

那伤。眞美

有22个优秀案例可参考真是太棒了！

    有8位网友表示赞同！

孤自凉丶

学习API 设计的资源不多啊，这篇文章很 timely!

    有19位网友表示赞同！

未来未必来

看起来可以让我快速了解一下优质API的设计原则。

    有9位网友表示赞同！

太易動情也是罪名

分享这些实践经验一定能让更多人做更好API设计。

    有12位网友表示赞同！

站上冰箱当高冷

希望这些案例能让我少走一些弯路！

    有6位网友表示赞同！

心亡则人忘

关注了很久，终于等到有关于API设计的详细文章了！

    有7位网友表示赞同！

清羽墨安

想成为一个优秀的开发人员，API 设计是必不可少的技能，赶紧看看这篇文章学习一下。

    有16位网友表示赞同！

冷落了♂自己·

22个案例应该涵盖很多不同类型的API设计吧？很期待能从中吸取经验。

    有6位网友表示赞同！

景忧丶枫涩帘淞幕雨

分享这种有价值的文章真的很棒，感谢作者的付出！

    有16位网友表示赞同！

绳情

学习新的知识总让人兴奋，期待这篇文章能让我的API设计能力提升很多。

    有19位网友表示赞同！

最怕挣扎

这个标题很吸引人，一定是一个非常好的文章。

    有20位网友表示赞同！

醉红颜

API 设计越来越重要了，这篇文章能让我对最新的趋势有一个更清楚的了解。

    有14位网友表示赞同！

赋流云

学习API 设计的最佳方法就是多实践，看看这些优秀案例会不会给我一些灵感！

    有19位网友表示赞同！

万象皆为过客

之前想写一个好用的API，但缺乏经验，希望能从这篇文章中找到答案。

    有20位网友表示赞同！

人心叵测i

看来这篇文章能帮我解决很多API设计的难题！

    有18位网友表示赞同！

最迷人的危险

终于可以告别文档阅读的枯燥感了，直接从案例入手学习API设计！

    有6位网友表示赞同！

微信名字

很希望作者能提供一些实用的代码示例，这样学习效果会更好。

    有17位网友表示赞同！