cf大秀直播平台

【编者的话】为瞎想REST API而纳闷?不要慌，这里有瞎想REST API的超实用提议!

也曾因为一个倒霉的API而感到不振吗?

在这个微处事的宇宙里，后端API的一致性瞎想是必不行少的。

今天，咱们将盘考一些可慑服的最好现实。咱们将保捏直爽和甜密-是以系好安全带，登程咯!

[[424906]]

领先先容一些术语

任何API瞎想皆慑服一种叫作念“面向资源瞎想”的原则

资源：资源是数据的一部分，举例：用户 聚合：一组资源称为聚合，举例：用户列表 URL：象征资源或聚合的位置，举例：/用户 1. 对URL使用kebab-case(短横线小写离隔神志)

举例，若是你思要得回订单列表。

不应该:

/systemOrders或/system_orders cf大秀直播平台

应该:

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

讨论复旧CORS允许的“*”着手，并通过灵验的OAuth令牌强制授权。

幸免将用户左证与原始考据相统一。

20.安全

在悉数端点、资源和处事上实施HTTPS (tls加密)。

强制并条目悉数回调url、推送示知端点和webhooks使用HTTPS。

21. 失实

当客户端向处事发出无效或不正确的恳求，或向处事传递无效或不正确的数据，而处事隔断该恳求时，就会出现失实，不祥更具体地说，出现处事失实。

例子包括无效的身份考据左证、不正确的参数、未知的版块id等。

当由于一个或多个处事失实而隔断客户端恳求时，一定要复返4xx HTTP失实代码。 讨论料理悉数属性，然后在单个反应中复返多个考据问题。 22. 黄金法例

若是您对API方式的决定有疑问，这些黄金轨则不错匡助咱们作念出正确的决定。

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

即是这么——若是你仍是走到了这一步，恭喜你!但愿你学到了一些东西。

但愿你渡过好意思好的一天!

译者：Mr.lzc，软件工程师、DevOpsDays、HDZ深圳中枢组织者，当今供职于华为，从事云野心责任，专注于K8s、微处事限度。

 

• cf大秀直播平台