我总结了22条API设计的最佳实践

曾经因为一个糟糕的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. 在你的响应体中包括总资源数