01 web api interfaces

WEB API Interface

Interface Description

Interface concept: the foreground and background information media interaction - url connection

https://api.map.baidu.com/place/v2/search

Interfaces:

url link - looks like a return data link url
Request method - get (check), post (increase), put (overall change), patch (local change), delete (delete)
Request Parameter - parameter splicing data packet parameters (urlencoded, form-data, json)
- ak：6E823f587c95f0148c19993539b99295
- region: Shanghai
- query: KFC
- output：json

Response Results - json response data

{
    "status":0,
    "message":"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"
        }
        ...
        ]
}

Development phase interface testing tool

Postman: Tool for testing interfaces

Download: https://www.postman.com/downloads/

WEB API Interface

Interface Description

Interface concept: the foreground and background information media interaction - url connection

https://api.map.baidu.com/place/v2/search

Interfaces:

url link - looks like a return data link url
Request method - get (check), post (increase), put (overall change), patch (local change), delete (delete)
Request Parameter - parameter splicing data packet parameters (urlencoded, form-data, json)
- ak：6E823f587c95f0148c19993539b99295
- region: Shanghai
- query: KFC
- output：json

Response Results - json response data

{
    "status":0,
    "message":"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"
        }
        ...
        ]
}

Development phase interface testing tool

Postman: Tool for testing interfaces

Download: https://www.postman.com/downloads/

Document Interface

Why write interface documentation

为什么要写接口：作为后台开发者，要将后台数据通过url链接反馈给前台
 
为什么要写文档：作为后台开发者，一定知道该url链接应该采用什么请求方式、提交哪些数据、返回了哪些结果
 
就像后台要将url链接改前台一样，前台知道应该访问什么链接，所以前台也应该知道采用什么请求方式，以及提交什么数据。

In other words, the interface document is to give developers the background, foreground developers, testers and other project-related projects while viewing the group, to facilitate team development (rules are specified in the background, the background document to write)

Approach to the preparation of the document

i）采用word编写
ii）drf框架有插件，可以根据cbv的类快速生成文档
iii）采用写文档的平台
YApi是去哪网大前端技术中心的一一个开源可视化接口管理平台。
不仅可以直接使用YApi自己提供的服务：http://yapi.demo.qunar.com/
也可以自己将YApi搭建到公司内部的服务器上

The writing process

i）先安装开发需要，完成接口的开发（设置后台url链接，设置请求方式、请求数据、响应结果）
ii）选择一个接口平台，将后台url链接，设置请求方式、请求数据、响应结果信息变成成文档即可

Interface Specification

1) Why should specify the interface specification

在前后台分离情况下，后台可以采用不同的后台运用，开发出类似的功能，所以前后台请求响应的规则是一致的；如果安装一套标准来编写接口，后台不管是什么语言，前台都可以采用一样的方式进行交互。反过来，后台也不需要管前台到底采用何种方式请求（页面、工具、代码）

2) Common Interface Specification: Restful interface specification

Url specifies how to write, meaning the way the request, the response data rules.

    i）url编写
        https协议 - 保证数据安全性
        api字眼 - 标识操作的是数据
        v1、v2字眼 - 数据的不同版本共存
        资源复数 - 请求的数据称之为资源
        拼接条件 - 过滤群查接口数据（https://api.baidu.com/books/?limit=3&ordering=-price）
 
    ii）请求方式
        /books/ - get - 群查
        /books/(pk)/ - get - 单查
        /books/ - post - 单增
        /books/(pk)/ - put - 单整体改
        /books/(pk)/ - patch - 单局部改
        /books/(pk)/ - delete - 单删
 
    iii）响应结果
        网络状态码与状态信息：2xx | 3xx | 4xx | 5xx
        数据状态码：前后台约定规则 - 0:成功 1:失败 2:成功无结果
        数据状态信息：自定义成功失败的信息解释(英文)
        数据本体：json数据
        数据子资源：头像、视频等，用资源的url链接