什么是RESTful API？

最新推荐文章于 2025-11-16 21:24:56 发布

原创最新推荐文章于 2025-11-16 21:24:56 发布 · 1.3k 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#java #restful

http 专栏收录该内容

1 篇文章

订阅专栏

RESTful API由Roy Fielding在其博士论文中提出，是一种基于HTTP协议的接口设计规则。它强调资源的定位，使用HTTP动词（GET、POST、PUT、PATCH、DELETE）操作资源。设计原则包括：资源与URI对应、统一接口、无状态等。URL不使用文件扩展名，返回数据通常为JSON格式。本文涵盖了URL格式、HTTP动词、参数命名规范及状态码的介绍。

一. 定义

Rest的全称是Representational State Transfer，2000年由Roy Fielding发表在他的博士论文中，首次提出了Restful的概念。Restful 做为一种接口的设计规则，基于HTTP协议 ，可以使用XML格式或JSON格式传输数据。对于使用restful这套规则定义开发的接口，我们称之为Restful API。
关于Restful的具体表现形式，简单可以用一句话概括：URL定位资源，使用HTTP请求（GET、POST、PUT、DELETE等）对资源进行操作。

二. 设计原则与规范

Restfu是典型的基于HTTP的协议，它有哪些设计原则和规范呢？

URL与资源：资源表示网络上的一个实体对象，可以是一个资产、一首歌曲或一种服务，资源总是以一定的格式来表现自己。通过定义一个URL指向资源，要访问资源时，只需要通过该资源所属的URL进行请求访问即可。一般来说，接口名称只能用名词，不可以用动词，根据HTTP的请求来进行操作，这样可以不在URL不暴露操作方式。
例如:http://www.kk.com/api/books 表示一个资源（书本）对象
统一接口规范：Restful架构应该遵循统一接口原则，统一接口包含了一组固定的预定义操作，不管是什么样的资源，都通过方式进行资源访问。在Restful API架构中，客户端通过HTTP协议，使用GET、POST、PUT和DELETE4种请求方式对服务端资源进行操作，GET用于获取资源，POST用来新建资源，PUT用来更新资源，DELETE用于删除资源。
无状态：从客户端到服务端的每个请求都是独立，请求中必须包含需要的所有信息，这也代表服务器不需要储存任何上下文信息，对于客户端来说，第一次请求和第100次请求都是相同的。在Restful 架构中，尽量避免使用session的方式，而是由客户端自己标识会话状态（token）。
除以上的操作规范外，另外还有一些要求，包括：
url不能使用大写字母；
不使用文件扩展名，如.php等；
可在url中增加api版本号等；
文本返回必须为Json格式。

三. URL格式标准、HTTP动词、参数命名规范

3.1 下面我们通过几个示例来了解下Restful API的格式定义方式

查看
GET http://api.xxx.com/users 查看所有用户信息
GET http://api.xxx.com/users/id 查看该id的用户信息
GET http://api.xxx.com/users?age=20& 根据搜索条件（age等于20)，显示符合条件的用户信息
创建
POST http://api.xxx.com/users创建用户，可在DATA处带需要的参数
更新
PUT http://api.xxx.com/users/id?name='张三'&age=20 修改该id的用户信息（name和age)
删除
DELETE http://api.xxx.com/users/id 删除该id的用户信息

对于资源的具体操作类型，由HTTP动词表示。

3.2 常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

还有两个不常用的HTTP动词。

HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

例子:

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：删除某个指定动物园的指定动物

3.3.3 参数命名规范

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

?limit=10：//指定返回记录的数量

?offset=10：//指定返回记录的开始位置。

?page=2&per_page=100：//指定第几页，以及每页的记录数。

?sortby=name&order=asc：//指定返回结果按照哪个属性排序，以及排序顺序。

?animal_type_id=1：//指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals与 GET /animals?zoo_id=ID的含义是相同的。

四.状态码（Status Codes）

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

200 OK - [GET]：//服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。

201 CREATED - [POST/PUT/PATCH]：//用户新建或修改数据成功。

202 Accepted - [*]：//表示一个请求已经进入后台排队（异步任务）

204 NO CONTENT - [DELETE]：//用户删除数据成功。

400 INVALID REQUEST - [POST/PUT/PATCH]：//用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。

401 Unauthorized - [*]：//表示用户没有权限（令牌、用户名、密码错误）。

403 Forbidden - [*] //表示用户得到授权（与401错误相对），但是访问是被禁止的。

404 NOT FOUND - [*]：//用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。

406 Not Acceptable - [GET]：//用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。

410 Gone -[GET]：//用户请求的资源被永久删除，且不会再得到的。

422 Unprocesable entity - [POST/PUT/PATCH] //当创建一个对象时，发生一个验证错误。

500 INTERNAL SERVER ERROR - [*]：//服务器发生错误，用户将无法判断发出的请求是否成功。