初识web API接口及Restful接口规范
一、web API接口
什么是web API接口？：
明确了请求方式，提供对应后台所需参数，请求url链接可以得到后台的响应数据
url : 返回数据的url
https://api.map.baidu.com/place/search
请求方式：
get，post,put,patch....
请求参数：json或xml格式的key-value类型数据
- ak：6E823f587c95f0148c19993539b99295
- region：上海
- query：肯德基
- output：json
响应结果：
返回json或xml格式的key-value类型数据
-
上方请求参数的output参数值决定了响应数据的格式
-
{ "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" } ... ] }
怎么写接口？：
参照某种规则（规范）书写url链接，同时根据规则制定请求方式，请求数据与响应结果
接口文档：
提供给前后台开发人员与测试人员查看
接口工具：
YAPI平台
专门写接口文档的YAPI平台 http://yapi.demo.qunar.com/
YApi是去哪儿网的前端技术中心的一个开源可视化接口管理平台。
- 创建接口项目
- 创建接口
- 编写接口
接口测试工具：Postman
Postman是一款接口调试工具，是一款免费的可视化软件，同时支持各种操作系统平台，是测试接口的首选工具。
Postman可以直接从官网：https://www.getpostman.com/downloads/下载获得，然后进行傻瓜式安装。
- 工作面板
- 简易的get请求
- 简易的post请求
- 案例：请求百度地图接口
接口规范：
webapi接口规范：restful
RESTful API介绍
RESTful介绍
REST与技术无关，代表的是一种软件架构风格，REST是Representational State Transfer的简称，中文翻译为“表征状态转移”或“表现层状态转化”。
推荐阅读 阮一峰 理解RESTful架构
RESTful API设计指南
推荐阅读 阮一峰 RESTful设计指南
API与用户的通信协议
总是使用HTTPs协议。
域名
用api关键字来标识接口url
注：看到api字眼，就代表该请求url链接是完成前后台数据交互的
版本
\1. 将版本信息放在URL中，如：
v1，v2代表不同数据版本的提现，前提是一种数据资源有多个版本
\2. 将版本信息放在请求头中。
url路径
视网络上任何东西都是资源，均使用名词表示（一般为复数形式）
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
在url链接中奖励不要出现操作资源的动词
错误示范：https://api.baidu.com/delete-user
特殊的接口可以出现动词，因为这些接口一般没有一个明确的资源，或是动词就是接口的核心含义
method请求方式
GET ：从服务器取出资源（一项或多项）
POST ：在服务器新建一个资源
PUT ：在服务器更新资源（客户端提供改变后的完整资源）
PATCH ：在服务器更新资源（客户端提供改变的属性）
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：指定筛选条件
状态码
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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
错误处理
状态码是4xx时，应返回错误信息，error当做key。
{
error: "Invalid API key"
}
返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范
GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档
{
"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"
}
...
]
}
Hypermedia API
RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
