API详解及使用

API的概念

API(Application Programming Interface应用程序编程接口)是一些预定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码或理解内部工作机制的细节

API的特点

API 是一个明确定义的接口,可以为其他软件提供特定服务
API可以小到只包含一个单独的函数,也可以达到包含数以百计的类、方法、全局函数、数据类型、枚举类型和常量
API的实现可以是私有的,也可以是开源的

API的分类

面向对象语言的 API ，比如java API列表
库与框架的 API，比如Windows API、Windows DirectX
API 与协议，比如LDAP应用程序接口
API 与设备接口，比如PC BIOS调用接口、ASPI for SCSI设备接口
Web API，比如Google地图API、新浪微博API、阿里云API市场

为什么要使用API?

快速扩展功能
避免"造轮子",提高开发效率
降低模块之间的耦合度

阿里云API市场提供1000+API服务

包含8个主要类目:

电子商务
金融理财
交通地理
企业管理
公共事务
气象水利
人工智能
生活服务

哪里找阿里云API市场
阿里云首页 -》云市场-》API

API请求与认证

Web API协议及HTTP请求

客户端向服务器发送一个请求

服务器给客户端一个响应,告诉客户端是否可以完成它请求的工作

HTTP请求包含的内容

URL（API调用地址）
请求方式 ：POST、GET、PUT、DELETE
Hearders（请求头）:包含很多附属信息，比如发起方(user-agent)、文档类型/认证信息等
Body（请求主体）：请求的主要数据 ，表单、图片等

API请求方式

请求方式告诉服务器客户端希望它采取什么动作。常见的请求方式有四种：

GET:请求服务器获取一个资源

POST:请求服务器创建一个资源

PUT:请求服务器更新或者编辑一个资源

DELETE:请求服务器删除一个资源

请求头与请求主体

请求头Hearders

提供请求的元信息,是一个简短的项目列表,其中有客户端发送请求的时间和请求主体的大小、身份认证等信息。
请求体Body
包含了客户端希望发送给服务器的数据

状态返回码

成功状态

成功调用API后，除了返回数据外，还会包含一个状态码，处理成功返回2xx：

服务端错误码

API未成功调用，则返回错误码。服务端错误码是5xx，表示服务不可用（此时一般建议重试或联系商品页面的API服务商）

客户端错误码

客户端错误码为4xx，表示业务报错。一般为参数错误,签名错误,请求方式有误或者流控限制
API数据格式

JSON格式

目前最新API大多使用json数据格式。JSON(JavaScript Object Notation)是一种轻量级的数据交换格式，采用完全独立于语言的文本格式，易于人阅读和编写，同时也易于机器解析和生成，是一种理想的数据交换语言。相对XML格式来说，较简洁

JSON数据格式表示方法

表示对象：json最常用的格式是对象的键值对

{"name":"黑龙江","city":"哈尔滨"}
    1

表示数组：和普通的JS数组一样，JSON表示数组的方式是使用方括号[]

{
    "name":"中国",
    "province":[
        {
        "name":"黑龙江",
        "city":"哈尔滨"
        },
        {
        "name":"广东",
        "city":"广州"
        }
    ]
}

API简单身份认证（APPCODE方式）

可以通过APPCODE的方式，实现到被调用接口的身份认证，获取访问相关API的调用权限。

使用方法：

请求Header中添加的Authorization字段；

配置Authorizatiion字段的值为"APPCODE+半角空格+APPCODE值"
格式：

Authorization:APPCODE AppCode值
示例
Authorization:APPCODE 3f2504xxxxxxxx3301

API签名认证（AppKey&AppSecret）

AppKey和AppSecret相当于当前账户的另一套账号和密码机制。在云市场购买API之后，就可以在控制台找到对应的AppKey和AppSecret。
API调试与调用
API调试

API调用步骤

获取API文档-》创建应用-》获取授权-》调用API

调用 api 三个基础条件

API:即将要调用的API，明确API参数定义
应用app：作为您调用API时的身份，有AppKey和AppSecert用于验证身份
Api 和 App 的权限关系：App想调用某个API需要具有该API的权限，这个权限通过授权的功能来建立

获取API文档

在云市场选择API，在API产品页面即可找到该API的使用说明(文档)
购买API服务成功后，进入云市场的管理控制台，就会看见购买的所有API服务。(如果还没开通API网关服务，那么就会同时开通API网关服务，让你使用更流畅)
可以跳转到API网关的控制台，在已购买API页面，展示购买的所有API服务列表，以及使用情况概况。

创建应用

应用APP是调用API服务时的身份。每个APP有一组Key和Secret，可以理解为账号密码，调用API的时候需要将AppKey做参数传入，AppSecret用于签名计算，网关会校验这对密钥对你进行身份认证。
可以在API网关控制台应用管理页面创建App，常见成功后，系统会为APP分配一对AppKey和AppSecret。

获得授权

授权，是指授予APP调用某个API的权限，您的APP需要获得API的授权才能调用该API。
如果你在市场购买了API，就可以指定将已购买的API授权给哪些APP，然后这些APP才能调用该API。
如果您没有APP，购买时云市场会为你创建一个APP，并且授权。

调用API

可以直接用API文档里提供的多语言调用示例来调用，如右图所示
也可以自行编辑HTTP(S)请求来调用API

API调用注意事项

每个账号下 APP 的个数上限为10个,app 名称应用为账号下唯一
调用 api 的流控限制为,单个IP,Qps 不超过100
你有权操作购买的 API 与 App 的授权和解除授权.由服务提供方授权给你的 APP 的API,你无权操作解除授权
你的请求需要包含签名信息
HTTP(S)请求来调用API

API调用注意事项

每个账号下 APP 的个数上限为10个,app 名称应用为账号下唯一
调用 api 的流控限制为,单个IP,Qps 不超过100
你有权操作购买的 API 与 App 的授权和解除授权.由服务提供方授权给你的 APP 的API,你无权操作解除授权
你的请求需要包含签名信息