什么是 REST API？

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

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

资源（Resource）：在 REST中，资源是任何可以通过 URI（统一资源标识符）进行访问的对象或实体。资源可以是数据对象、服务、文件等。
URI（统一资源标识符）：每个资源都有一个唯一的 URI，用于标识资源。例如，/books/1可能代表一本书，/users/2可能代表一个用户。
HTTP方法：REST API使用HTTP方法来执行对资源的操作。常用的方法包括：
- GET：检索资源。
- POST：创建新资源。
- PUT：更新现有资源。
- PATCH：部分更新资源。
- DELETE：删除资源。
无状态（Statelessness）：每个请求从客户端发送到服务器时，必须包含处理该请求所需的所有信息。服务器不应在请求之间存储任何客户端状态。
表现层状态转移（Representational State Transfer）：客户端与服务器之间的交互通过资源的表现层进行。表现层可以是JSON、XML、HTML等格式。客户端通过 HTTP请求来获取、更新或删除资源的表现层。
统一接口（Uniform Interface）：REST通过定义一组标准操作（如HTTP方法）来提供统一接口，使得系统的不同部分可以通过一致的方式进行交互。
缓存（Cacheable）：服务器响应应该被标记为可缓存或不可缓存，以提高性能和减少网络流量。
分层系统（Layered System）：客户端不需要知道它直接连接到的是最终服务器还是中间服务器（如代理服务器）。分层系统有助于提高系统的可伸缩性和安全性。
按需代码（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格式，因为它易于阅读和解析。

错误信息：在响应体中包含详细的错误信息。例如：

{
    "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，持续输出硬核文章。

什么是 REST API？ 如何设计 REST API？