RESTful API 的协议格式和交互模型-JavaScript中文网-JavaScript教程资源分享门户

RESTful API 是指一种基于 REST（Representational State Transfer，表述性状态转移）原则构建的 Web API。其核心概念是资源（Resource），通过 URI（Uniform Resource Identifier，统一资源标识符）来唯一定位资源，通过 HTTP（Hypertext Transfer Protocol，超文本传输协议）协议来转移资源的表述（Representations）。

协议格式

RESTful API 的协议格式包括资源的 URI、HTTP 方法、HTTP 头部（Headers）和 HTTP 消息体（Message Body）。

资源的 URI

URI 是 RESTful API 唯一标识资源的方式，其格式如下：

[scheme:]//host[:port]/[path]/[resource-id]

其中，scheme 可选，表示 URI 所使用的协议，默认为 http；host 表示主机名或 IP 地址；port 可选，表示连接的端口号，默认为协议默认端口；path 表示资源所在的路径，以正斜杠 '/' 开始；resource-id 表示资源的标识符，以字符串形式表述。

例如，一个博客的文章资源可以用以下 URI 标识：

http://example.com/api/articles/12345

HTTP 方法

HTTP 方法用于定义对资源的操作类型，常用的 HTTP 方法有 GET、POST、PUT、PATCH 和 DELETE。其对应的语义如下：

GET：获取资源的表述。
POST：创建新资源。
PUT：更新已存在的资源。
PATCH：部分更新已存在的资源。
DELETE：删除已存在的资源。

HTTP 头部

HTTP 头部用于传递与消息相关的元数据，可以包括请求头部和响应头部。常用的 HTTP 头部有如下几种：

Accept：指明客户端能够处理的数据类型。
Content-Type：指明实体（HTTP 消息的消息体）的类型。
Authorization：为请求认证凭据，比如 token 等。
ETag：实体标签，用于缓存资源，可以在响应头部和请求头部中使用。
If-None-Match：标识客户端请求的资源与服务器上的资源是否一致。
Cache-Control：控制缓存的行为。

HTTP 消息体

HTTP 消息体是可选的，用于传递资源的表述，通常使用 JSON 或 XML 格式。

交互模型

RESTful API 的交互模型通过 HTTP 方法的使用来定义资源的状态转移。常见的资源状态转移有以下几种：

获取资源

获取某个资源的表述，使用 HTTP 方法 GET：

GET /api/articles/12345 HTTP/1.1
Host: example.com

创建资源

创建新资源，使用 HTTP 方法 POST，同时在请求消息体中包含资源表述：

POST /api/articles HTTP/1.1
Host: example.com
Content-Type: application/json

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

更新资源

更新已有资源，使用 HTTP 方法 PUT，同时在请求消息体中包含新的资源表述：

PUT /api/articles/12345 HTTP/1.1
Host: example.com
Content-Type: application/json

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

部分更新资源

部分更新已有资源，使用 HTTP 方法 PATCH，同时在请求消息体中包含需要更新的属性：

PATCH /api/articles/12345 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "title": "Updated Article"
}

删除资源

删除已有资源，使用 HTTP 方法 DELETE：

DELETE /api/articles/12345 HTTP/1.1
Host: example.com

示例代码

以下是一个使用 Express 框架构建的简单 RESTful API 示例，用于管理文章资源：

// www.javascriptcn.com code example
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.json());

let articles = [
  { id: '1', title: 'Article 1', content: '...' },
  { id: '2', title: 'Article 2', content: '...' },
  { id: '3', title: 'Article 3', content: '...' }
];

app.get('/api/articles', (req, res) => {
  res.json(articles);
});

app.get('/api/articles/:id', (req, res) => {
  const article = articles.find(article => article.id === req.params.id);
  res.json(article);
});

app.post('/api/articles', (req, res) => {
  const article = req.body;
  article.id = String(articles.length + 1);
  articles.push(article);
  res.json(article);
});

app.put('/api/articles/:id', (req, res) => {
  const index = articles.findIndex(article => article.id === req.params.id);
  articles[index] = { ...req.body, id: req.params.id };
  res.json(articles[index]);
});

app.patch('/api/articles/:id', (req, res) => {
  const index = articles.findIndex(article => article.id === req.params.id);
  articles[index] = { ...articles[index], ...req.body };
  res.json(articles[index]);
});

app.delete('/api/articles/:id', (req, res) => {
  articles = articles.filter(article => article.id !== req.params.id);
  res.sendStatus(204);
});

app.listen(3000, () => console.log('Listening on http://localhost:3000/'));

在这个示例中，使用 Express 框架监听请求，根据不同的 HTTP 方法和 URI 进行响应，同时使用 bodyParser 中间件来解析 HTTP 消息体。其中，使用了数组 articles 来存储文章资源的数据，模拟了 API 与数据库之间的交互。

学习和指导意义

RESTful API 是 Web 开发中非常重要的一部分，是前后端分离和 API 优先开发的基础，也是微服务和单页应用的核心。学习和掌握 RESTful API 的设计和开发原则，对于提高 Web 应用的开发效率、减少耦合和提升用户体验都有很大的帮助。

在设计和开发 RESTful API 的过程中，需要注重资源的唯一标识符和状态转移的语义。同时，需要考虑安全性、可测性和扩展性等方面的因素，采用合适的 HTTP 方法、HTTP 头部和消息体格式，遵循设计原则和最佳实践，才能开发出高质量和易于使用的 RESTful API。

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

RESTful API 的协议格式和交互模型