首页 > 技术文章 > RESTful规范

peter-web 2021-08-23 18:00 原文

什么是RESTful

一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。

一、URI规范

1.不用大写;

2.用中杠 - 不用下杠 _ ;

3.参数列表要encode;

4.URI中的名词表示资源集合,使用复数形式。

5.在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词(特殊情况可以使用动词),而且所用的名词往往与数据库的表格名对应。

资源集合 vs单个资源

URI表示资源的两种方式:资源集合、单个资源。

资源集合:

       /zoos //所有动物园

       /zoos/1/animals //id为1的动物园中的所有动物

单个资源:

       /zoos/1//id为1的动物园

       /zoos/1;2;3//id为1,2,3的动物园

避免层级过深的URI

在url中表达层级,用于 按实体关联关系进行对象导航 ,一般根据id导航。

过深的导航容易导致url膨胀,不易维护,如 GET /zoos/1/areas/3/animals/4 ,尽量使用查询参数代替路径中的实体导航,如 GET/animals?zoo=1&area=3 ;

二、   版本

应该将API的版本号放入到URI中

https://api.example.com/v1/zoos

三、 Request

HTTP方法

通过标准HTTP方法对资源CRUD:

GET:查询(从服务器取出资源一项或多项)

GET /zoos

GET /zoos/1

GET/zoos/1/employees

 

POST:创建单个新资源。 POST一般向“资源集合”型uri发起

POST/animals  //新增动物

POST/zoos/1/employees //为id为1的动物园雇佣员工

PUT:更新单个资源(全量),客户端提供完整的更新后的资源。与之对应的是 PATCH,PATCH负责部分更新,客户端提供要更新的那些字段。 PUT/PATCH一般向“单个资源”型uri发起

PUT/animals/1

PUT /zoos/1

 

DELETE:删除

DELETE/zoos/1/employees/2

DELETE/zoos/1/employees/2;4;5

DELETE/zoos/1/animals  //删除id为1的动物园内的所有动物

 

HEAD / OPTION/ PATCH用的不多,就不多解释了。

HEAD:获取资源的元数据

OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的

PATCH:在服务器更新资源(客户端提供改变的属性)

 

摘自:https://www.cnblogs.com/fu-yong/p/9052623.html

   https://www.ruanyifeng.com/blog/2014/05/restful_api.html

      https://www.jianshu.com/p/a34f18d30aaa

推荐阅读