通用技术 测试平台搭建 (三):RESTful API 接口设计标准及规范

· 2021年03月28日 · 863 次阅读

我们测试平台目前采用的是前后端分离架构,后端的接口一般都是采用的 restful API 接口设计标准及规范。这里就简单说下跟我们平台有关的 resultful 相关知识

一.版本

将版本信息放在 URL 中,如:

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

v1,v2 代表不同数据版本的提现,前提是一种数据资源有多个版本

二.method 请求方式

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

POST :在服务器新建一个资源

PUT :在服务器更新资源(客户端提供改变后的完整资源)

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

DELETE :从服务器删除资源

应用场景:GET 一般用于读取服务器资源,不改变服务器资源;POST 一般用于插入数据,PUT 一般用于更新数据,DELETE 一般用于删除数据

三.过滤

通过在 url 上传参的形式传递搜索条件

https://api.example.com/v1/zoos?limit=10:指定返回记录的数量

https://api.example.com/v1/zoos?offset=10:指定返回记录的开始位置

https://api.example.com/v1/zoos?page=2&per_page=100:指定第几页,以及每页的记录数

https://api.example.com/v1/zoos?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序

https://api.example.com/v1/zoos?animal_type_id=1:指定筛选条件

四.安全性和幂等性

安全性:不会改变资源状态,可以理解为只读的;

幂等性:执行 1 次和执行 N 次,对资源状态改变的效果是等价的

安全性和幂等性均不保证反复请求能拿到相同的 response。以 DELETE 为例,第一次 DELETE 返回 200 表示删除成功,第二次返回 404 提示资源不存在,这是允许的。

五.状态码

200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。

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

202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)

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

301:永久重定向

302:暂时重定向

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 - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。

共收到 0 条回复 时间 点赞
关闭了讨论 03月28日 16:20
重新开启了讨论 03月28日 16:20
需要 登录 后方可回复, 如果你还没有账号请点击这里 注册