江苏龙网

  1. 主页 > 生活百科 > >

22 条 API 设计技巧，总结得很好

API

原文链接：
https://mp.weixin.qq.com/s/z_VTBydcQKQ9R-gGH5C6Dw
在这个微服务的世界里，后端API的一致性设计是必不可少的 。
今天，我们将讨论一些可遵循的最佳实践 。我们将保持简短和甜蜜——所以系好安全带，出发咯！
首先介绍一些术语任何API设计都遵循一种叫做“面向资源设计”的原则：
  • 资源：资源是数据的一部分，例如：用户
  • 集合：一组资源称为集合，例如：用户列表
  • URL：标识资源或集合的位置，例如：/user
1. 对URL使用kebab-case（短横线小写隔开形式）例如，如果你想要获得订单列表 。
不应该：
/systemOrders或/system_orders应该：
/system-orders2. 参数使用camelCase（驼峰形式）例如，如果你想从一个特定的商店购买产品 。
不应该：
/system-orders/{order_id}或者：
/system-orders/{OrderId}应该：
/system-orders/{orderId}3. 指向集合的复数名称如果你想获得系统的所有用户 。
不应该：
GET /user或：
GET /User应该：
GET /users4. URL以集合开始，以标识符结束如果要保持概念的单一性和一致性 。
不应该：
GET /shops/:shopId/category/:categoryId/price这很糟糕，因为它指向的是一个属性而不是资源 。
应该：
【22 条 API 设计技巧，总结得很好】GET /shops/:shopId/或GET /category/:categoryId5. 让动词远离你的资源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/

22 条 API 设计技巧，总结得很好

文章插图
 
拥有良好而详细的文档可以为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


推荐阅读


上一篇：python包管理工具pip config详解

下一篇：提升百度品牌推广效果的方法