亲宝软件园·资讯

展开

初识web API接口及Restful接口规范

tomjoy 人气:2

一、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.comhttps://img.qb5200.com/download-x/downloads/下载获得,然后进行傻瓜式安装。

  • 工作面板

  • 简易的get请求

  • 简易的post请求

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

接口规范:

​ webapi接口规范:restful

RESTful API介绍

RESTful介绍

REST与技术无关,代表的是一种软件架构风格,REST是Representational State Transfer的简称,中文翻译为“表征状态转移”或“表现层状态转化”。

推荐阅读 阮一峰 理解RESTful架构

RESTful API设计指南

推荐阅读 阮一峰 RESTful设计指南

API与用户的通信协议

总是使用HTTPs协议。

域名

用api关键字来标识接口url

https://api.example.com

https://example.org/api/

注:看到api字眼,就代表该请求url链接是完成前后台数据交互的

版本

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

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

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

​ 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.comhttps://img.qb5200.com/download-x/delete-user

特殊的接口可以出现动词,因为这些接口一般没有一个明确的资源,或是动词就是接口的核心含义

  • https://api.baidu.com/place/search
  • https://api.baidu.com/login

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"
}}

加载全部内容

相关教程
猜你喜欢
用户评论