怎样判断一个 API 是不是 RESTful API
RESTful API 是目前最为流行的一种 API 设计风格,它以无状态、可缓存、可计算性、统一接口等特性,实现了前后端之间的分离,提高了系统的可扩展性、可维护性和可复用性。那么,我们怎样判断一个 API 是不是 RESTful API 呢?下面让我来详细介绍一下。
1. URI 设计
RESTful API 中的 URI 是整个 API 的核心部分,因为它能够确定资源的位置和动作,所以 URI 设计应该要满足以下几个条件:
- URI 可读性高,能够让人们看到 URI 即知道资源类型;
- URI 层级结构清晰,不超过三级;
- URI 中的动词应该尽可能的采用 HTTP 协议中的动词 (GET、POST、PUT、DELETE、PATCH);
- URI 采用名词复数形式,表达出访问资源的集合;
- URI 中可以加入查询参数,但尽可能少用,特别是与分页相关的参数应该放在header中;
- 对于一些特殊符号,如"-"、"."、"_" 应该采用适当约定,如"_should_be_used" 或 "should-be-used"。
以下是一个 URI 设计规范的示例:
GET /api/v1/users # 获取用户列表 POST /api/v1/users # 创建用户 GET /api/v1/users/1 # 获取 id 为 1 的用户信息 PUT /api/v1/users/1 # 更新 id 为 1 的用户信息 DELETE /api/v1/users/1 # 删除 id 为 1 的用户信息
2. HTTP 方法
HTTP 方法是 RESTful API 中最为重要的方法,它指明了客户端对资源执行的操作类型。以下是 RESTful API 中常用的 HTTP 方法:
- GET:获取资源;
- POST:创建资源;
- PUT:更新资源;
- DELETE:删除资源;
- PATCH:更新部分资源;
- HEAD:获取资源的元数据;
- OPTIONS:获取资源的可用方法。
如果一个 API 没有正确地实现 HTTP 方法,那么它就不是一个真正的 RESTful API。
3. 状态码
RESTful API 中的状态码是用来表示服务器响应的状态,它能够让客户端了解到请求成功或失败、资源是否存在等信息。以下是一些常见的状态码:
- 200 OK:请求成功;
- 201 CREATED:创建资源成功;
- 204 NO CONTENT:删除成功;
- 400 BAD REQUEST:请求格式不正确;
- 401 UNAUTHORIZED:没有权限;
- 404 NOT FOUND:请求资源不存在;
- 405 METHOD NOT ALLOWED:该请求方法不被允许;
- 500 INTERNAL SERVER ERRROR:服务器端错误。
4. 媒体类型
RESTful API 中使用了媒体类型(Media Type)来表达出返回数据的格式,包括了以下两个方面:
- 格式:JSON、XML 等;
- 编码方式:GZIP、DEFLATE 等。
媒体类型通常在 HTTP 的 Header 中进行设置,例如:
Accept: application/json Content-Type: application/json
总结
一个 API 是否是 RESTful API,需要从 URI 设计、HTTP 方法、状态码以及媒体类型等多个方面来判断。通过领会到 RESTful API 设计原则,我们可以具备更好的 API 设计意识,更好地提升 API 的可用性、可扩展性和可维护性。
参考示例代码
以下是一个使用 Express 实现一个简单的 RESTful API 的示例代码:
// www.javascriptcn.com code example
const express = require('express')
const app = express()
const bodyParser = require('body-parser')
app.use(bodyParser.json())
const users = [
{id: 1, name: '张三', age: 23},
{id: 2, name: '李四', age: 24},
{id: 3, name: '王五', age: 25},
]
app.get('/api/v1/users', (req, res) => {
res.status(200).json(users)
})
app.get('/api/v1/users/:id', (req, res) => {
const user = users.find(user => user.id === +req.params.id)
if (!user) {
res.status(404).send('用户不存在')
} else {
res.status(200).json(user)
}
})
app.post('/api/v1/users', (req, res) => {
const user = {id: users.length + 1, ...req.body}
users.push(user)
res.status(201).json(user)
})
app.put('/api/v1/users/:id', (req, res) => {
const index = users.findIndex(user => user.id === +req.params.id)
if (index === -1) {
res.status(404).send('用户不存在')
} else {
users[index] = {...users[index], ...req.body}
res.status(200).json(users[index])
}
})
app.delete('/api/v1/users/:id', (req, res) => {
const index = users.findIndex(user => user.id === +req.params.id)
if (index === -1) {
res.status(404).send('用户不存在')
} else {
users.splice(index, 1)
res.status(204).send()
}
})
const PORT = 3000
app.listen(PORT, () => {
console.log(`Example app listening at http://localhost:${PORT}`)
})来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/64eb3e50f6b2d6eab35df3a7