为什么要使用 RESTful 架构?
REST 是 Representational State Transfer 的缩写,如果一个架构符合 REST 原则,就称它为 RESTful 架构
RESTful 架构可以充分的利用 HTTP 协议的各种功能,是 HTTP 协议的最佳实践
RESTful API 是一种软件架构风格、设计风格,可以让软件更加清晰,更简洁,更有层次,可维护性更好
RESTful API 请求设计
GET /zoos 列出所有动物园
POST /zoos 新建一个动物园
GET /zoos/:id 获取某个指定动物园的信息
PUT /zoos/:id 更新某个指定动物园的全部信息
PATCH /zoos/:id 更新某个指定动物园的部分信息
DELETE /zoos/:id 删除某个动物园
GET /zoos/:id/animals 列出某个指定动物园的所有动物
DELETE /zoos/:id/animals/:id 删除某个指定动物园的指定动物
请求 = 动词 + 宾语
动词 使用五种 HTTP 方法,对应 CRUD 操作。
宾语 URL 应该全部使用名词复数,可以有例外,比如搜索可以使用更加直观的 search 。
过滤信息(Filtering) 如果记录数量很多,API应该提供参数,过滤返回结果。 ?limit=10 指定返回记录的数量 ?offset=10 指定返回记录的开始位置。
RESTful API 响应设计
使用 HTTP 的状态码
客户端的每一次请求,服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。
五大类状态码,总共100多种,覆盖了绝大部分可能遇到的情况。每一种状态码都有约定的解释,客户端只需查看状态码,就可以判断出发生了什么情况。API 不需要1xx状态码。
1xx 相关信息
2xx 操作成功
3xx 重定向
4xx 客户端错误
5xx 服务器错误
POST /articles
Authorization:eyJ0eXAiOiJKV1QiLCJhbGciOiJI......
content-type: application/json
 
{
    "title":"舟夜书所见"
    "content":"月黑见渔灯,孤光一点萤。微微风簇浪,散作满河星。"
}
201 Created
{
    "id":"123e4567-e89b-12d3-a456-426655440000"
    "title":"舟夜书所见"
    "content":"月黑见渔灯,孤光一点萤。微微风簇浪,散作满河星。"
    "create_time":"2026-11-25 20:45:27"
}
服务器回应数据
客户端请求时,要明确告诉服务器,接受 JSON 格式,请求的 HTTP 头的 ACCEPT 属性要设成 application/json
服务端返回的数据,不应该是纯文本,而应该是一个 JSON 对象。服务器回应的 HTTP 头的 Content-Type 属性要设为 application/json
错误处理 如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将 error 作为键名,出错信息作为键值即可。 {error: "Invalid API key"}
认证 RESTful API 应该是无状态,每个请求应该带有一些认证凭证。推荐使用 JWT 认证,并且使用 SSL
Hypermedia 即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么
相关文章
查看更多
谁在使用 RESTful API ?
RESTful API 作为一种流行的 API 设计风格,被广泛的使用在各种系统的设计中

微软 API 设计指南

Github REST API v3

白宫 Web API 标准

SpaceX-API

HEROKU API 设计指南

WordPress REST API 手册

夜间模式切换
回到顶部