RESTful API 的思考 - 从资源到动词-JavaScript中文网-JavaScript教程资源分享门户

什么是 RESTful API？

RESTful API 是一种基于 HTTP 协议的 API 设计风格，它通过 URL 来表示资源，通过 HTTP 方法来表示对资源的操作。具体来说，RESTful API 的设计原则包括以下几点：

使用 HTTP 方法来表示对资源的操作，包括 GET、POST、PUT、DELETE 等；
使用 URL 来表示资源的位置，包括主机名、端口号、路径和查询参数；
使用 HTTP 头部来表示请求和响应的元数据，包括 Content-Type、Accept、Authorization 等；
使用 HTTP 状态码来表示请求和响应的结果，包括 200、201、400、401、404 等。

为什么需要 RESTful API？

RESTful API 的设计原则具有以下优点：

轻量级：使用 HTTP 协议作为传输协议，无需额外的协议和框架；
可扩展性：使用 URL 来表示资源位置，可以轻松地添加、修改和删除资源；
可缓存性：使用 HTTP 头部来表示缓存策略，可以避免重复请求和响应；
平台无关性：使用 HTTP 协议作为传输协议，可以在不同的平台和语言之间进行通信。

如何设计 RESTful API？

在设计 RESTful API 时，需要遵循以下几个原则：

1. 从资源出发

RESTful API 的设计应该从资源出发，而不是从操作出发。具体来说，应该先确定需要暴露哪些资源，然后再确定对这些资源可以进行哪些操作。

例如，一个博客系统中可能包含文章、评论、用户等资源，那么我们可以设计以下 API：

GET /articles：获取所有文章；
POST /articles：创建一篇新文章；
GET /articles/:id：获取一篇指定 ID 的文章；
PUT /articles/:id：更新一篇指定 ID 的文章；
DELETE /articles/:id：删除一篇指定 ID 的文章；
GET /comments：获取所有评论；
POST /comments：创建一条新评论；
GET /comments/:id：获取一条指定 ID 的评论；
PUT /comments/:id：更新一条指定 ID 的评论；
DELETE /comments/:id：删除一条指定 ID 的评论；
GET /users：获取所有用户；
POST /users：创建一个新用户；
GET /users/:id：获取一个指定 ID 的用户；
PUT /users/:id：更新一个指定 ID 的用户；
DELETE /users/:id：删除一个指定 ID 的用户。

2. 使用 HTTP 方法

RESTful API 的设计应该使用 HTTP 方法来表示对资源的操作。具体来说，应该使用以下几个 HTTP 方法：

GET：获取资源；
POST：创建资源；
PUT：更新资源；
DELETE：删除资源。

例如，对于上面的博客系统，我们可以使用以下 HTTP 方法：

GET /articles：获取所有文章；
POST /articles：创建一篇新文章；
GET /articles/:id：获取一篇指定 ID 的文章；
PUT /articles/:id：更新一篇指定 ID 的文章；
DELETE /articles/:id：删除一篇指定 ID 的文章。

3. 使用 URL

RESTful API 的设计应该使用 URL 来表示资源的位置。具体来说，应该使用以下几个 URL：

主机名：表示服务器的域名或 IP 地址；
端口号：表示服务器的端口号，默认为 80；
路径：表示资源的路径，由斜杠分隔；
查询参数：表示请求的参数，由问号和键值对组成，多个参数之间用 & 符号分隔。

例如，对于上面的博客系统，我们可以使用以下 URL：

GET http://example.com/articles：获取所有文章；
POST http://example.com/articles：创建一篇新文章；
GET http://example.com/articles/123：获取一篇 ID 为 123 的文章；
PUT http://example.com/articles/123：更新一篇 ID 为 123 的文章；
DELETE http://example.com/articles/123：删除一篇 ID 为 123 的文章。

4. 使用 HTTP 头部

RESTful API 的设计应该使用 HTTP 头部来表示请求和响应的元数据。具体来说，应该使用以下几个 HTTP 头部：

Content-Type：表示请求或响应的内容类型，例如 application/json、application/xml 等；
Accept：表示请求或响应的可接受内容类型，例如 application/json、application/xml 等；
Authorization：表示请求的身份验证信息，例如 Basic、Bearer 等；
Cache-Control：表示请求或响应的缓存策略，例如 no-cache、max-age 等。

例如，对于上面的博客系统，我们可以使用以下 HTTP 头部：

GET http://example.com/articles
- Accept: application/json
POST http://example.com/articles
- Content-Type: application/json
- Authorization: Bearer token
GET http://example.com/articles/123
- Accept: application/json
PUT http://example.com/articles/123
- Content-Type: application/json
- Authorization: Bearer token
DELETE http://example.com/articles/123
- Authorization: Bearer token

5. 使用 HTTP 状态码

RESTful API 的设计应该使用 HTTP 状态码来表示请求和响应的结果。具体来说，应该使用以下几个 HTTP 状态码：

200：表示请求成功；
201：表示资源创建成功；
400：表示请求参数错误；
401：表示未经身份验证；
404：表示资源不存在；
500：表示服务器内部错误。

例如，对于上面的博客系统，我们可以使用以下 HTTP 状态码：

GET http://example.com/articles
- 200 OK
POST http://example.com/articles
- 201 Created
GET http://example.com/articles/123
- 200 OK
PUT http://example.com/articles/123
- 200 OK
DELETE http://example.com/articles/123
- 200 OK

总结

RESTful API 是一种基于 HTTP 协议的 API 设计风格，它通过 URL 来表示资源，通过 HTTP 方法来表示对资源的操作。在设计 RESTful API 时，需要从资源出发，使用 HTTP 方法、URL、HTTP 头部和 HTTP 状态码来进行设计。同时，还需要注意安全性、可扩展性和可缓存性等方面的问题。

示例代码如下：

// javascriptcn.com 代码示例
const express = require('express')
const bodyParser = require('body-parser')
const app = express()

// 解析请求体中的 JSON 数据
app.use(bodyParser.json())

// 获取所有文章
app.get('/articles', (req, res) => {
  // TODO: 获取所有文章
  res.status(200).json({ articles: [] })
})

// 创建一篇新文章
app.post('/articles', (req, res) => {
  const article = req.body
  // TODO: 创建一篇新文章
  res.status(201).json({ article })
})

// 获取一篇指定 ID 的文章
app.get('/articles/:id', (req, res) => {
  const id = req.params.id
  // TODO: 获取一篇指定 ID 的文章
  res.status(200).json({ article: { id } })
})

// 更新一篇指定 ID 的文章
app.put('/articles/:id', (req, res) => {
  const id = req.params.id
  const article = req.body
  // TODO: 更新一篇指定 ID 的文章
  res.status(200).json({ article: { id, ...article } })
})

// 删除一篇指定 ID 的文章
app.delete('/articles/:id', (req, res) => {
  const id = req.params.id
  // TODO: 删除一篇指定 ID 的文章
  res.status(200).json({})
})

app.listen(3000, () => {
  console.log('Server is running at http://localhost:3000')
})

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