探究 RESTful API 接口设计原则-JavaScript中文网-JavaScript教程资源分享门户

RESTful API 是一种基于 HTTP 协议的 Web API 设计风格。它的设计原则可以帮助我们创建出易于理解、可维护、可扩展、可重用的 API 接口。本文将介绍 RESTful API 的设计原则及其实践方法。

1. 资源

RESTful API 的核心概念是资源。资源是指我们要向用户暴露的信息或操作，例如用户、文章、评论等。每个资源都有一个唯一的标识符（URI），它可以用来表示该资源的状态。

在设计 RESTful API 的时候，我们应该将资源作为整个 API 的核心，尽可能地将资源的状态和操作抽象出来，并以统一的方式进行表示。

例如，我们可以创建一个文章资源，它的 URI 可以是 /articles。客户端可以使用 GET 方法来获取文章列表，使用 POST 方法来创建新的文章。

// javascriptcn.com 代码示例
GET /articles HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "title": "Hello World",
    "content": "..."
  },
  {
    "id": 2,
    "title": "RESTful API",
    "content": "..."
  }
]

// javascriptcn.com 代码示例
POST /articles HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "title": "New Article",
  "content": "..."
}

HTTP/1.1 201 Created
Location: /articles/3

2. 表现层

RESTful API 的另一个核心概念是表现层。表现层是指客户端与服务器之间传输的数据格式，例如 JSON、XML、HTML 等。在 RESTful API 中，服务器应该将资源以一种标准的表现形式向客户端返回，客户端可以根据自己的需要来选择接受哪种表现形式。

例如，我们可以在 HTTP 头部中指定 Accept 属性来告诉服务器我们希望接受哪种表现形式。

GET /articles HTTP/1.1
Host: example.com
Accept: application/json

服务器可以根据请求头部中的 Accept 属性来决定返回哪种表现形式的数据。

// javascriptcn.com 代码示例
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "title": "Hello World",
    "content": "..."
  },
  {
    "id": 2,
    "title": "RESTful API",
    "content": "..."
  }
]

3. 动词

RESTful API 中的动词指的是 HTTP 方法，包括 GET、POST、PUT、PATCH、DELETE 等。每种方法都有其特定的语义，应该根据语义来选择相应的方法。

例如，我们可以使用 GET 方法来获取资源，使用 POST 方法来创建资源，使用 PUT 或 PATCH 方法来更新资源，使用 DELETE 方法来删除资源。

// javascriptcn.com 代码示例
GET /articles/1 HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "title": "Hello World",
  "content": "..."
}

// javascriptcn.com 代码示例
POST /articles HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "title": "New Article",
  "content": "..."
}

HTTP/1.1 201 Created
Location: /articles/3

// javascriptcn.com 代码示例
PUT /articles/1 HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "title": "New Title",
  "content": "..."
}

HTTP/1.1 204 No Content

DELETE /articles/1 HTTP/1.1
Host: example.com
Authorization: Bearer <token>

HTTP/1.1 204 No Content

4. 连通性

RESTful API 应该是无状态的，客户端每次请求都应该包含足够的信息来让服务器处理该请求。服务器不应该保存客户端的状态，客户端也不应该依赖服务器的状态。

例如，我们可以在 HTTP 头部中使用 Authorization 属性来传递身份验证信息，客户端每次请求都应该包含该信息。

GET /articles HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <token>

5. 缓存

RESTful API 应该支持缓存，客户端可以在请求头部中指定 Cache-Control 属性来告诉服务器是否需要缓存该资源。服务器可以在响应头部中添加 Expires、Cache-Control 属性来告诉客户端该资源的过期时间。

例如，我们可以在请求头部中指定 Cache-Control 属性来告诉服务器我们需要缓存该资源。

GET /articles/1 HTTP/1.1
Host: example.com
Accept: application/json
Cache-Control: max-age=3600

服务器可以在响应头部中添加 Expires、Cache-Control 属性来告诉客户端该资源的过期时间。

// javascriptcn.com 代码示例
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600
Expires: Wed, 21 Oct 2020 07:28:00 GMT

{
  "id": 1,
  "title": "Hello World",
  "content": "..."
}

6. 总结

本文介绍了 RESTful API 的设计原则及其实践方法。通过将资源作为整个 API 的核心，以统一的方式进行表示，以及根据客户端的需要来选择表现形式，选择合适的 HTTP 方法，保持无状态和支持缓存等方式，我们可以创建出易于理解、可维护、可扩展、可重用的 API 接口。

参考代码：https://github.com/ruanyf/restful-tutorial

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/657a0d98d2f5e1655d43c53e