为什么要使用 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-08-03 15:26:08"
}
服务器回应数据
客户端请求时，要明确告诉服务器，接受 JSON 格式，请求的 HTTP 头的 ACCEPT 属性要设成 application/json
服务端返回的数据，不应该是纯文本，而应该是一个 JSON 对象。服务器回应的 HTTP 头的 Content-Type 属性要设为 application/json
错误处理 如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可。 {error: "Invalid API key"}
认证 RESTful API 应该是无状态，每个请求应该带有一些认证凭证。推荐使用 JWT 认证，并且使用 SSL
Hypermedia 即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么
相关文章
跟 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 设计规范，用于 Web 数据接口的设计。 它的大原则容易把握，但是细节不容易做对。本文总结 RESTful 的设计细节，介绍如何设计出易于理解和使用的 API。 一、URL 设计 1.1 动词 + 宾语 RESTful 的核心思想就是，客户端发出的数据操作指令都是”动词 + 宾语”的结构。比如，GET /article […]
详解 RESTful API 中的动词覆盖
今天，写篇文章介绍一下 RESTful API 中的动词覆盖吧。 在开发各种小程序的时候，总是会遇到不能正常支持 HTTP 请求的平台，比如支付宝小程序只支持 GET 和 POST 请求，这时候充分利用 HTTP 请求方法的 RESTful API 就会遇到问题，不支持 PUT, PATCH, DELETE 请求，该怎么办呢？嗯，使用动词覆盖。 什么是动词覆盖 我最初遇到不支持全部 HTTP 请求 […]
查看更多
谁在使用 RESTful API ?
RESTful API 作为一种流行的 API 设计风格，被广泛的使用在各种系统的设计中

微软 API 设计指南

Github REST API v3

白宫 Web API 标准

SpaceX-API

HEROKU API 设计指南

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