RESTful接口API设计规范

最新推荐文章于 2024-01-07 17:17:55 发布

MattenLi

最新推荐文章于 2024-01-07 17:17:55 发布

阅读量335

点赞数

分类专栏：实习笔记文章标签： RESTful

本文链接：https://blog.csdn.net/MattenLi/article/details/84988574

版权

实习笔记专栏收录该内容

1 篇文章 0 订阅

订阅专栏

一、基本概念

1.REST （Representational State Transfer）

即表现层的状态转移，指的是一组架构约束和原则。

是不是看着一脸懵逼，先了解下面的概念，再来理解到底什么是REST

2.资源（Rescources）

在整个架构约束和原则中的主体，即资源的表现层状态转移。

所谓“资源”，就是网络上的一个实体，或者说是网络上的一个具体信息。“资源”可以是一段文字、一个对象、一种服务，你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

3.表现（Representation）

资源"具体呈现出来的形式，叫做它的"表现层"（Representation）

比如，文本的几种表现形式（.txt，.html，.json，...）、图片的几种表现（.jpg，.png，.gif，...）

4.状态转换（State Transfer）

可以简单理解为客户端与服务器的一种交互过程。

互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"，即（REST）。

举个例子：用户的数据存放在服务端，当客户端需要获取用户数据时，通过get请求去服务器获取数据，服务器端将用户数据以json的表现形式返回给客户端。

客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。

二、RESTful API规范

1.协议

必须使用，https规范

2.域名

最好将api部署在专用域名之下

https://aip.example.com

若小项目，可放在主域名之后

https://www.example.com/aip/...

3.版本信息

建议将API的版本放入URL中

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

注：也可以将版本信息放入HTTP头信息中，但不如放入URL方便和直观。Github就是采用这种做法

4.端点（EndPoint）

表示API的具体网址

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

eg：有一个API提供公司信息，而公司（company）内部有部门（organization）信息，员工（employee）信息等等，那它的路径应该遵循下面规范

https://api.example.com/v1/companys
https://api.example.com/v1/animals
https://api.example.com/v1/employees

5.HTTP动词

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

常见有以下五个操作：

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

还有两个下面两个操作

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

套用上述网址，可以有以下例子

GET /companys：列出所有公司
POST /companys：新建一个公司
GET /companys/id：获取某个指定公司的信息
PUT /companys/id：更新某个指定公司的信息（提供该动物园的全部信息）
PATCH /companys/id：更新某个指定公司的信息（提供该动物园的部分信息）
DELETE /companys/id：删除某个公司
GET /companys/id/employees：列出某个指定公司的所有员工
DELETE /companys/id/employees/id：删除某个指定公司的指定员工

6.消息结果过滤

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

下面是一些常见的参数

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

7.返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档