RESTful API 中的请求和响应格式-JavaScript中文网-JavaScript教程资源分享门户

RESTful API 是目前最流行的 Web API 设计架构之一，它以 HTTP 协议为基础，提供了一组标准的请求和响应格式，使得开发者能够快速、灵活地构建高效的 Web 服务。在本文中，我们将深入探讨 RESTful API 中的请求和响应格式，包括 HTTP 方法、请求头、请求体、响应状态码、响应头和响应体等内容。

HTTP 方法

HTTP 协议定义了若干个请求方法或动作，其中最常用的包括 GET、POST、PUT、DELETE 和 PATCH 等，它们分别表示从服务器获取资源、向服务器提交更新、向服务器新增资源、从服务器删除资源和向服务器部分修改资源等操作。在 RESTful API 中，每个资源都应该有一个唯一的标识符——URI（统一资源标识符），同时应该有一个对应的 HTTP 方法来进行操作。例如：

GET /api/users：获取所有用户列表
POST /api/users：新增一个用户
PUT /api/users/{id}：更新一个用户的信息
DELETE /api/users/{id}：删除一个用户

请求头

HTTP 请求头包含了一些元数据，用于指定请求的属性和选项。常用的请求头包括：

Accept：指定客户端期望接收的响应数据类型和格式，例如 application/json、text/xml 等
Authorization：指定请求的身份验证信息，例如 Basic、Bearer 等
Content-Type：指定请求体的格式和编码方式，例如 application/json、multipart/form-data 等
Cookie：指定客户端的会话标识信息，通常用于保持登录状态
User-Agent：指定客户端的类型和版本信息，例如 Mozilla/5.0、Chrome/92.0.4515.159 等

可以通过开发者工具或第三方库来自定义请求头，例如：

// www.javascriptcn.com code example
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'User-Agent': 'RESTful API Client/1.0',
  },
  body: JSON.stringify({
    name: 'Alice',
    age: 20,
  }),
};

fetch('/api/users', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error));

请求体

HTTP 请求体包含了一些数据，用于向服务器提交表单、文件、JSON 等信息。在 RESTful API 中，请求体通常用于 POST、PUT 和 PATCH 等方法。请求体的格式和编码方式取决于请求头的 Content-Type 值。常用的请求体格式包括：

application/json：发送 JSON 格式的数据，通常使用 JSON.stringify 将 JavaScript 对象转换为字符串
application/x-www-form-urlencoded：发送 URL 编码格式的数据，通常使用 URLSearchParams 将 JavaScript 对象转换为字符串
multipart/form-data：发送表单数据和文件，通常使用 FormData 构造函数将表单项转换为 FormData 对象

例如，发送 JSON 数据的示例代码如下：

// www.javascriptcn.com code example
const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Alice',
    age: 20,
  }),
};

fetch('/api/users', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error));

发送 URL 编码格式的数据的示例代码如下：

// www.javascriptcn.com code example
const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    name: 'Alice',
    age: '20',
  }),
};

fetch('/api/users', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error));

发送表单数据和文件的示例代码如下：

// www.javascriptcn.com code example
const form = document.querySelector('form');
const input = document.querySelector('input[type="file"]');

form.addEventListener('submit', event => {
  event.preventDefault();

  const formData = new FormData(form);
  formData.append('avatar', input.files[0]);

  const options = {
    method: 'POST',
    body: formData,
  };

  fetch('/api/users', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error(error));
});

响应状态码

HTTP 响应状态码表示服务器对请求的处理结果，常用的状态码和含义包括：

200 OK：请求成功，响应包含所请求的数据
201 Created：请求成功，服务器创建了新的资源并返回了标识符
204 No Content：请求成功，但是响应不包含任何数据
400 Bad Request：请求失败，客户端发送的数据格式不正确或者缺少必要的请求参数
401 Unauthorized：请求失败，客户端未提供正确的身份验证信息
403 Forbidden：请求失败，客户端没有权限执行该请求
404 Not Found：请求失败，请求的资源不存在或者 URL 格式不正确
500 Internal Server Error：请求失败，服务器内部发生了错误

在处理响应时，通常需要根据状态码进行判断和处理，例如：

// www.javascriptcn.com code example
fetch('/api/users/123')
  .then(response => {
    if (!response.ok) {
      throw new Error(response.statusText);
    }

    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error(error));

响应头

HTTP 响应头包含了一些元数据，用于指定响应的属性和选项。常用的响应头包括：

Content-Type：指定响应体的格式和编码方式，例如 application/json、text/html 等
Set-Cookie：指定服务器返回的会话标识信息，通常用于创建新的会话或者更新会话状态
ETag：指定响应内容的唯一标识符，可以用于缓存和验证数据
Last-Modified：指定响应内容的最后修改时间，可以用于缓存和验证数据

可以通过 response 对象的 headers 属性来获取响应头的值，例如：

// www.javascriptcn.com code example
fetch('/api/users')
  .then(response => {
    const contentType = response.headers.get('Content-Type');
    const etag = response.headers.get('ETag');

    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error(error));

响应体

HTTP 响应体包含了服务器返回的数据，通常采用 JSON、XML、HTML 等格式。在 RESTful API 中，响应体应该根据请求的结果进行标准化，例如 GET 请求返回资源列表或者资源单个实例，POST 请求返回新增的资源标识符，PUT 和 PATCH 请求返回空的响应体或者更新后的资源实例，DELETE 请求返回空的响应体或者删除成功的标识符。例如：

GET /api/users：返回用户列表

// www.javascriptcn.com code example
{
  "count": 100,
  "results": [
    {
      "id": 1,
      "name": "Alice",
      "age": 20
    },
    {
      "id": 2,
      "name": "Bob",
      "age": 30
    }
  ]
}

POST /api/users：返回新增用户的标识符

{
  "id": 101
}

PUT /api/users/101：返回更新后的用户实例

{
  "id": 101,
  "name": "Charlie",
  "age": 40
}

DELETE /api/users/101：返回空的响应体

由于响应体的格式和内容可能会影响客户端的使用体验和性能，因此需要在设计 API 时合理地定义响应体的结构和内容，以达到最佳的交互效果。同时，还需要考虑缓存、压缩、分页等方案来提升响应体的处理效率。

结语

本文深入介绍了 RESTful API 中的请求和响应格式，包括 HTTP 方法、请求头、请求体、响应状态码、响应头和响应体等内容。这些标准化的格式和规范使得开发者能够快速构建高效的 Web 服务，提高开发效率和代码质量。同时，本文也提供了一些示例代码和最佳实践，可供开发者参考和借鉴。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/67d81298a941bf7134e69c5a

RESTful API 中的请求和响应格式

HTTP 方法

请求头

请求体

响应状态码

响应头

响应体

结语

接着读