当前位置: 首页 > 图灵资讯 > 技术篇> REST API 设计和命名约定指南

REST API 设计和命名约定指南

来源:图灵教育
时间:2024-09-18 15:18:36

rest api 设计和命名约定指南

RESTful有效设计 API对于创建可扩展、可维护、易于使用的系统至关重要。虽然有一些标准,但许多标准不是严格的规则,而是指导 API 设计的最佳实践。广泛使用 API 架构模式是 MVC(模型-视图-控制器),但本身无法解决 API 更精细的设计方面,如命名和结构。本文将逐步介绍建筑 REST API 基本准则。

  1. 命名协议和资源设计 API 资源代表系统中的实体,如“用户”,通常围绕资源定义、“产品”或“订单”。资源可以是单个项目或集合,API 与这些资源互动应提供直观清晰的方式。

主要原则:面向资源:围绕资源而不是操作设计 API。资源应该被视为名词,而不是动词。例如:

/users 用于访问用户集合。 /users/{userId} 用于访问特定用户。 一致性:API 它应该是直观的。如果用户能从头开始 /users 为了获得资源列表,他们应该期望通过添加标识符来获得单个资源:/users/{userId}.

收集和单一资源:

复数名词表示资源集合:/users、/products。 单个资源通过附加资源的唯一标识符表示:/users/{userId}、/products/{productId}.

  1. HTTP 方法定义操作,而不是 URI 正在执行的操作(无论是检索数据、创建新项目还是更新现有数据)都不应嵌入 URI 中。相反,HTTP 决定操作的方法。

常见的 HTTP 方法及其用例: GET:从服务器中检索数据。

示例:GET /products 返回所有产品列表。 示例: GET /users/{userId} 有指定的检索 userId 的用户。 POST:在服务器上创建新的资源。

示例:POST /users 创建新用户。 PUT:用新数据替换现有资源(完全更新)。

示例:PUT /users/{userId} 用新数据完全替换用户数据。 PATCH:现有资源(部分更新)部分更新。

示例:PATCH /users/{userId} 仅更新指定的属性,如电话号码。 DELETE:删除资源。

示例:DELETE /users/{userId} 删除指定 userId 的用户。

  1. REST 中的无状态 REST API 它应该是无状态的,这意味着每个人都是无状态的 API 调用必须包含服务器处理请求所需的所有信息。这确保每个请求都是自给自足的,并且不依赖于以前的请求。

例子:当发出 GET 在获取用户详细信息时,即使之前的请求已经验证了用户的身份,请求也必须包含所需的授权令牌。这在分布式系统中非常重要,因为不同的请求可能会到达不同的服务器。

  1. 避免特定于服务器的数据存储 任何单个 API 请求不应依赖于在特定服务器上存储临时数据。在分布式系统中,传输请求可能通过任何服务器传输,因此无论哪个服务器处理请求,都应实现相同的结果。这就是为什么会话状态不应该存储在单独的服务器上。

解决方案:对于会话管理,请使用集中或分布式存储系统(如 Redis)或者没有状态身份验证机制(例如(例如) JWT(JSON Web Token))。

  1. 资源与数据库表 您的 API 数据库表和设计不应在数据库表中进行 API 端点之间有一对一的映射。 API 有意义的资源应该在逻辑上公开,这些资源可以从多个表或源中组合数据。

示例: GET /orders/{orderId} 结合订单,可以检索订单的详细信息order_items 以及客户表中的信息。

  1. 数据类型的灵活性 REST API 不受数据库数据类型或表结构的限制。你可以是最适合你的 API 用消费者的方式建立你的反应。虽然 JSON 它是最常用的格式,但如有必要,您可以自由返回 XML 或 CSV 等待其他格式的数据。

示例:GET /reports/{reportId} 根据请求中的查询参数或标头,端点可以返回各种格式(JSON、CSV、PDF)的报告。 API 结构示例 为了将这些原则联系起来,这里有一个遵循这些最佳实践的原则 API 结构示例:

GET /products:检索所有产品。 GET /products/{productId}:详细检索特定产品的信息。 POST /products:创造新产品。 PUT /products/{productId}:用productid代替产品。 PATCH /products/{productId}:部分更新产品。 DELETE /products/{productId}:删除产品。 在这种结构中,资源被明确定义,HTTP 该方法规定了要采取的操作,以确保 API 干净直观。

**结论 **设计 RESTful API 不仅涉及路由的创建和处理 HTTP 方法。注重资源,利用资源。 HTTP 操作方法,遵守无状态,可创建直观、可维护、可扩展的方法 API。请记住,API 随着系统的发展,应灵活独立于特定的数据库结构,以提供更多的适应性。

遵循这些协议可以确保你 API 设计效率高,用户友好,最终增强 API 开发人员和消费者的体验。

以上是REST API 请关注图灵教育的其他相关文章,详细介绍设计和命名协议指南!

上一篇:

Spring框架中的控制反转

下一篇:

返回列表