为什么要使用 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方法，使得用户不查文档，也知道下一步应该做什么
相关文章
当后端响应的 HTTP 状态一律 200
RESTful API 执行 delete 返回204无法获取 Body
在浏览器中 RESTful API 执行 delete 返回204无法获取 Body，也就是说执行成功后，只能返回空的。无法获取到返回的 Body 内容。 使用 restclient 可以获取到 body。 大多数人都认为204是成功删除的良好响应代码，因为通常没有充分的理由在删除某些内容后返回响应正文。 所以，如果 delete 操作成功且响应主体为空，则返回204。如果 delete 操作成功 […]
跟 Github 学习设计不符合 CRUD 情况的 RESTful API
在实际资源操作中，总会有一些不符合 CRUD（Create-Read-Update-Delete） 的情况，一般有几种处理方法。 1. 使用 POST 为需要的动作增加一个 endpoint，使用 POST 来执行动作，比如: POST /resend 重新发送邮件。 2. 增加控制参数 添加动作相关的参数，通过修改参数来控制动作。比如一个博客网站，会有把写好的文章“ […]
什么是 RESTful API 的幂等性
什么接口幂等性？ 幂等性原本是数学中的含义，表达式的是N次变换与1次变换的结果相同。 RESTFul API 中的幂等性是指调用某个方法1次或N次对资源产生的影响结果都是相同的。 比如，RESTFul API 中的 GET 方法是查询资源，不会对资源产生影响，所以它是符合幂等性的； 再比如，RESTful API 中的 DELETE 方法是查询数据，每次都应该返回 status=204。 接口符合 […]
HTTP 协议入门
HTTP 协议是互联网的基础协议，也是网页开发的必备知识，最新版本 HTTP/2 更是让它成为技术热点。 本文介绍 HTTP 协议的历史演变和设计思路。 一、HTTP/0.9 HTTP 是基于 TCP/IP 协议的应用层协议。它不涉及数据包（packet）传输，主要规定了客户端和服务器之间的通信格式，默认使用80端口。 最早版本是1991年发布的0.9版。该版本极其简单，只有一个命令GET。 上面 […]
JSON Web Token 入门教程
JSON Web Token（缩写 JWT）是目前最流行的跨域认证解决方案，本文介绍它的原理和用法。 一、跨域认证的问题 互联网服务离不开用户认证。一般流程是下面这样。 1、用户向服务器发送用户名和密码。 2、服务器验证通过后，在当前对话（session）里面保存相关数据，比如用户角色、登录时间等等。 3、服务器向用户返回一个 session_id，写入用户的 Cookie。 4、用户随后的每一次 […]
查看更多
谁在使用 RESTful API ?
RESTful API 作为一种流行的 API 设计风格，被广泛的使用在各种系统的设计中

微软 API 设计指南

Github REST API v3

白宫 Web API 标准

SpaceX-API

HEROKU API 设计指南

WordPress REST API 手册
夜间模式切换
回到顶部