如何设计 REST API？

发表于 分类于 阅读次数： 本文字数： 2.8k 阅读时长 ≈ 3 分钟

嗨，你好啊，我是猿java

这篇文章我们将分析什么是 REST API？ 如何设计优雅的 REST API？

什么是 REST API？

REST API，全称 Representational State Transfer Application Programming Interface，它是一种基于 REST架构风格的应用程序编程接口。

REST是一种用于构建分布式系统的架构风格，通过利用 HTTP协议来定义和访问资源。 以下是 REST API的一些关键特征和概念：

  1. 资源（Resource）：在 REST中，资源是任何可以通过 URI（统一资源标识符）进行访问的对象或实体。资源可以是数据对象、服务、文件等。

  2. URI（统一资源标识符）：每个资源都有一个唯一的 URI，用于标识资源。例如，/books/1可能代表一本书，/users/2可能代表一个用户。

  3. HTTP方法：REST API使用HTTP方法来执行对资源的操作。常用的方法包括：

    • GET：检索资源。
    • POST：创建新资源。
    • PUT：更新现有资源。
    • PATCH：部分更新资源。
    • DELETE：删除资源。

  4. 无状态（Statelessness）：每个请求从客户端发送到服务器时，必须包含处理该请求所需的所有信息。服务器不应在请求之间存储任何客户端状态。

  5. 表现层状态转移（Representational State Transfer）：客户端与服务器之间的交互通过资源的表现层进行。表现层可以是JSON、XML、HTML等格式。客户端通过 HTTP请求来获取、更新或删除资源的表现层。

  6. 统一接口（Uniform Interface）：REST通过定义一组标准操作（如HTTP方法）来提供统一接口，使得系统的不同部分可以通过一致的方式进行交互。

  7. 缓存（Cacheable）：服务器响应应该被标记为可缓存或不可缓存，以提高性能和减少网络流量。

  8. 分层系统（Layered System）：客户端不需要知道它直接连接到的是最终服务器还是中间服务器（如代理服务器）。分层系统有助于提高系统的可伸缩性和安全性。

  9. 按需代码（Code on Demand）（可选）：服务器可以通过传输可执行代码（如JavaScript）到客户端来扩展其功能。

REST API 设计规范

在设计 REST API时，通常会遵循以下一些设计规范：

资源的定义和URI设计

  • Json格式：API交互中应该使用 JSON格式，不要使用纯文本。
  • 资源命名：使用名词来命名资源，避免使用动词。例如，使用/books而不是/getBooks。
  • 复数形式：对资源使用复数形式。例如，/books而不是/book。
  • 层次结构：使用层次结构表示资源之间的关系。例如，/authors/{authorId}/books表示特定作者的书籍。
  • 避免深度嵌套：尽量避免过深的嵌套层次，保持URI简洁。

HTTP方法的使用

  • GET：用于检索资源。例如，GET /books检索所有书籍，GET /books/{id}检索特定ID的书籍。
  • POST：用于创建新资源。例如，POST /books在书籍集合中创建一本新书。
  • PUT：用于更新整个资源。例如，PUT /books/{id}更新特定ID的书籍。
  • PATCH：用于部分更新资源。例如，PATCH /books/{id}部分更新特定ID的书籍。
  • DELETE：用于删除资源。例如，DELETE /books/{id}删除特定ID的书籍。

状态码和错误处理

  • 2xx 成功：
    • 200 OK：请求成功。
    • 201 Created：资源成功创建。
    • 204 No Content：请求成功但没有返回内容（通常用于DELETE请求）。
  • 4xx 客户端错误：
    • 400 Bad Request：请求格式错误或参数无效。
    • 401 Unauthorized：未提供身份验证凭据或凭据无效。
    • 403 Forbidden：凭据有效但无权限访问资源。
    • 404 Not Found：资源不存在。
    • 409 Conflict：请求冲突（如重复创建）。
    • 422 Unprocessable Entity：表明请求实体的语法是正确的，但语义上存在问题。
  • 5xx 服务器错误：
    • 500 Internal Server Error：服务器内部错误。
    • 503 Service Unavailable：服务不可用。
    • 504 Gateway Timeout：网关超时，表示服务器在作为网关或代理时，未能在规定时间内从上游服务器（例如HTTP、FTP、LDAP服务器）或辅助服务器（例如DNS服务器）接收到响应。

4. 统一资源接口

  • 一致性：确保API的行为一致。例如，所有的POST请求都返回201 Created。
  • HATEOAS：Hypermedia as the Engine of Application State。响应中包含链接，指向相关资源，使客户端可以动态发现API的功能。

5. 请求和响应格式

  • 内容类型：使用Content-Type头指定请求和响应的格式。常用的格式包括application/json。
  • 数据格式：尽量使用JSON格式，因为它易于阅读和解析。
  • 错误信息：在响应体中包含详细的错误信息。例如：
    1
    2
    3
    4
    5
    6
    {
        "error": "Invalid payload.",
        "detail": {
            "name": "This field is required."
        }
    }

6. 过滤、排序和分页

  • 过滤：使用查询参数进行过滤。例如，GET /books?author=Anna过滤作者为 Anna的书籍。
  • 排序：使用查询参数进行排序。例如，GET /books?sort=title按书名排序。
  • 分页：使用查询参数进行分页。例如，GET /books?page=1&page_size=10获取第一页的 10本书。

7. 安全性

  • HTTPS：始终使用HTTPS来加密数据传输，确保安全性。
  • 身份验证：使用标准的身份验证机制，如OAuth 2.0、JWT（JSON Web Tokens）等。
  • 权限控制：确保只有有权限的用户才能访问或修改资源。

8. 文档和版本控制

  • 文档：提供详细的API文档，描述每个端点、请求参数、响应格式和示例。
  • 版本控制：在URI或HTTP头中包含版本信息。例如，/v1/books或使用Accept头中的版本信息。

9. 处理尾随斜杠

  • 一致性：选择是否在URI中使用尾随斜杠，并保持一致性。例如，始终使用/books/或始终使用/books。
  • 重定向：如果客户端使用了错误的格式，优雅地重定向到正确的 URI。

总结

REST API 是日常开发中很常见的一个 API架构风格，如果能够遵循这些设计规范，你将创建一个更加健壮、直观和易于维护的REST API。

学习交流

如果你觉得文章有帮助，请帮忙转发给更多的好友，或关注公众号：猿java，持续输出硬核文章。

drawing