Restful接口规范

Posted 2020-11-22 zx125

常用接口文档编写工具

Yapi：简单

showdoc：自定义强

swagger

接口测试工具

浏览器

postman

各种抓包工具（fidder）

Restful接口规范

REST

Representational State Transfer(表述性状态转移)

核心

统一接口规范

规范

1.网络上的所有事物都被抽象为资源

2.每个资源都有一个唯一的资源标识符（books,cars)

3.同一个资源具有多种表现形式(xml,json等)

4.所有的操作都是无状态的

5.CRUD(POST GET PUT DELETE)

实例-url设计

数据的安全保障
url链接?般都采?https协议进?传输
注：采?https协议，可以提?数据交互过程中的安全性
接?特征表现
?api关键字标识接?url：

https://api.baidu.com
https://www.baidu.com/api
注：看到api字眼，就代表该请求url链接是完成前后台数据交互的

多数据版本共存
在url链接中标识数据版本

https://api.baidu.com/v1
https://api.baidu.com/v2
注：url链接中的v1、v2就是不同数据版本的体现（只有在?种数据资源有多版本情况
下）

数据即是资源
接??般都是完成前后台数据的交互，交互的数据我们称之为资源

https://api.baidu.com/users
https://api.baidu.com/books
https://api.baidu.com/book
注：?般提倡?资源的复数形式，在url链接中奖励不要出现操作资源的动词，错误?
范：https://api.baidu.com/delete-user
特殊的接?可以出现动词，因为这些接??般没有?个明确的资源，或是动词就是接?
的核?含义
https://api.baidu.com/place/search
https://api.baidu.com/login

资源操作由请求?式决定(高复用接口)
操作资源?般都会涉及到增删改查，我们提供请求?式来标识增删改查动作

https://api.baidu.com/books - get请求：获取所有书
https://api.baidu.com/books/1 - get请求：获取主键为1的书
https://api.baidu.com/books - post请求：新增?本书书
https://api.baidu.com/books/1 - put请求：整体修改主键为1的书
https://api.baidu.com/books/1 - patch请求：局部修改主键为1的书
https://api.baidu.com/books/1 - delete请求：删除主键为1的书

总结如下

GET    :    /users       - 获取用户列表
GET    :    /users/1     - 获取 Id 为 1 的用户
POST   :    /users       - 创建一个用户
PUT    :    /users/1     - 替换 Id 为 1 的用户
PATCH  :    /users/1     - 修改 Id 为 1 的用户
DELETE :    /users/1     - 删除 Id 为 1 的用户 

关于响应状态码参考以下链接

https://www.cnblogs.com/zx125/p/11701091.html

响应结果

响应数据要有状态码、状态信息以及数据本?

{
    "status":0,
    "msg":"ok",
    "results":[
        {
            "name":"肯德基(罗餐厅)",
            "location":{
                "lat":31.415354,
                "lng":121.357339
            },
            "address":"月罗路2380号",
            "province":"上海市",
            "city":"上海市",
            "area":"宝山区",
            "street_id":"339ed41ae1d6dc320a5cb37c",
            "telephone":"[phone]",
            "detail":1,
            "uid":"339ed41ae1d6dc320a5cb37c"
        }
        ...
    ]
}

要url请求的资源需要访问资源的请求链接

{
    "status":0,
    "msg":"ok",
    "results":[
        {
            "name":"肯德基(罗餐厅)",
            "img":"https://image.baidu.com/kfc/001.png"
        }
        ...
    ]
}

参考链接

https://segmentfault.com/a/1190000020373356?utm_source=tag-newest

https://www.cnblogs.com/xiaoyuanqujing/articles/11869751.html