接口规范

Web应用模式

在开发Web应用中，有两种应用模式：

  1. 前后端不分离[客户端看到的内容和所有界面效果都是由服务端提供出来的。

前后端不分离

  1. 前后端分离【把前端的界面效果(html，css，js分离到另一个服务端，python服务端只需要返回数据即可)】

    前端形成一个独立的网站，服务端构成一个独立的网站

前后端分离

Web API接口

1.什么是Web API接口

通过网络，规定了前后台信息交互规则的url链接，也就是前后台信息交互的媒介

Web API接口和一般的url链接还是有区别的，Web API接口简单概括有下面四大特点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"status":0,
"message":"ok",
"results":[
    {
        "name":"肯德基(罗餐厅)",
        "location":{
            "lat":31.415354,
            "lng":121.357339
        },
        "address":"月亮路38号",
        "province":"上海市",
        "city":"上海市",
        "area":"宝山区",
        "street_id":"339ed41ae1d6dc320a5cb37c",
        "telephone":"(021)56761006",
        "detail":1,
        "uid":"339ed41ae1d6dc320a5cb37c"
    }
    ...
    ]
}

2.接口文档的编写：YApi

YApi是去哪网大前端技术中心的一个开源可视化接口管理平台。

YApi项目可以搭建在任何本地或云服务器上，完成后台项目开发时的接口编写。为开发、测试等人员提供可视化的接口预览。

去哪同时在网上提供了YApi的测试网站：http://yapi.demo.qunar.com/，我们可以通过测试网站了解YApi是如何进行接口的编写的

  • 访问测试网站

img

  • 创建接口项目

img

  • 创建接口

img

  • 编写接口

img

img

img

3.接口测试工具：Postman

Postman是一款接口调试工具，是一款免费的可视化软件，同时支持各种操作系统平台，是测试接口的首选工具。

Postman可以直接从官网：https://www.getpostman.com/downloads/下载获得，然后进行傻瓜式安装。

  • 工作面板

img

  • 简易的get请求

img

  • 简易的post请求

img

  • 案例：请求百度地图接口

img

Restful 接口规范

1.什么是RESTful

一切皆资源

RESTful : 面向资源架构（ROA：Resource Oriented Architecture)

  • REST与技术无关，代表的是一种软件架构风格，REST是Representational State Transfer的简称，中文翻译为表征状态转移
  • REST从资源的角度类审视整个网络，它将分布在网络中某个节点的资源通过URL进行标识，客户端应用通过URL来获取资源的表征，获得这些表征致使这些应用转变状态
  • REST与技术无关，代表的是一种软件架构风格，REST是Representational State Transfer的简称，中文翻译为表征状态转移
  • 所有的数据，不过是通过网络获取的还是操作（增删改查）的数据，都是资源，将一切数据视为资源是REST区别与其他架构风格的最本质属性
  • 对于REST这种面向资源的架构风格，有人提出一种全新的结构理念，即：面向资源架构（ROA：Resource Oriented Architecture）

RESTful作为目前最流行的 API 设计规范，一定有着它独有的魅力：强大、简介、易上手。

这种风格的理念认为后端开发任务就是提供数据的，对外提供的是数据资源的访问接口，所以在定义接口时，客户端访问的URL路径就表示这种要操作的数据资源。

而对于数据资源分别使用POST、DELETE、GET、UPDATE等请求动作来表达对数据的增删查改。

GET/students获取所有学生
请求方法请求地址后端操作
POST/students增加学生
GET/students/获取编号为pk的学生
PUT/students/修改编号为pk的学生
DELETE/students/删除编号为pk的学生

restful规范是一种通用的规范，不限制语言和开发框架的使用。事实上，我们可以使用任何一门语言，任何一个框架都可以实现符合restful规范的API接口。

参考文档：http://www.runoob.com/w3cnote/restful-architecture.html

1.1幂等性

接口实现过程中，会存在幂等性。所谓幂等性是指代客户端发起多次同样请求时，是否对于服务端里面的资源产生不同结果。如果多次请求，服务端结果还是一样，则属于幂等接口，如果多次请求，服务端产生结果是不一样的，则属于非幂等接口。

请求方式是否幂等是否安全
GET幂等安全
POST不幂等不安全
PUT/PATCH幂等不安全
DELETE幂等不安全

2.URL设计

2.1 数据的安全保障

  • url链接一般都采用https协议进行传输

    注：采用https协议，可以提高数据交互过程中的安全性

2.2 接口特征表现

2.3 多数据版本共存

2.4 数据即是资源

2.5 资源操作由请求方式决定

3.响应状态码

3.1 正常响应

  • 响应状态码2xx
    • 200：常规请求
    • 201：创建成功

3.2 重定向响应

  • 响应状态码3xx
    • 301：永久重定向
    • 302：暂时重定向

3.3 客户端异常

  • 响应状态码4xx
    • 403：请求无权限
    • 404：请求路径不存在
    • 405：请求方法不存在

3.4 服务器异常

  • 响应状态码5xx
    • 500：服务器异常

4.响应结果

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "status": 0,
    "msg": "ok",
    "results":[
        {
            "name":"肯德基(罗餐厅)",
            "location":{
                "lat":31.415354,
                "lng":121.357339
            },
            "address":"月罗路2380号",
            "province":"上海市",
            "city":"上海市",
            "area":"宝山区",
            "street_id":"339ed41ae1d6dc320a5cb37c",
            "telephone":"(021)56761006",
            "detail":1,
            "uid":"339ed41ae1d6dc320a5cb37c"
        }
        ...
        ]
}

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

1
2
3
4
5
6
7
8
9
10
11
{
    "status": 0,
    "msg": "ok",
    "results":[
        {
            "name":"肯德基(罗餐厅)",
            "img": "https://image.baidu.com/kfc/001.png"
        }
        ...
        ]
}