API

· 2020-07-31 · # API # api # 简介 # 详情

API:简介

概念

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

特点

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

为什么使用

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

云API

阿里云API市场
电子商务
金额理财
交通地理
企业管理
公共事业
气象水利
人工智能
生活服务

API:请求与认证

Web API 协议及 HTTP 请求

Web API 协议

Web API一般采用HTTP作为底层协议，HTTP请求机制如下：

客户端向服务器发送一个请求
服务器给客户端一个相应，告诉客户端十分可以完成它请求的工作

HTTP请求包含的内容

为了构造有效的请求，客户端需要包含四个部分：

URL（API调用地址）
Method（请求方式）
Headers（请求头）
Body（请求主体）

API 请求方式

API请求方式

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

GET：请求服务器获取一个资源
POST：请求服务器创建一个新的资源
PUT：请求服务器编辑或更新一个已存在的资源
DELETE：请求服务器删除一个资源

请求头与请求主体

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

状态返回码

状态码 - 成功状态

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

HTTP 状态码	语义
200 OK - [GET]	服务器成功返回用户请求的数据
201 CREATED - [POST/PUT/PATCH]	用户新建或修改数据成功
202 Accepted - [*]	表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]	用户删除数据成功

状态码 - 服务端错误码

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

错误代码	HTTP状态码	语义	建议方案
Internal Error	500	API 网关内部错误	建议重试
Failed To Invoke Backend Swevice	500	底层服务错误	API提供者底层服务错误，建议重试，如果多次尝试仍然不可用，可联系API服务商解决
Service Unavailable	503	服务不可用	建议稍后重试
Async Service	504	后端服务超时	建议稍后重试

状态码 - 客户端错误码

客户端错误码位4xx，表示业务报错。此时一般位参数错误、签名错误、请求方式有误或被流控限制业务类错误。建议详细查看错误码，针对性解决问题。
参考：错误代码表 https://help.aliyun.com/document_detail/43906.html
注意：有些API自定义了错误码，具体请查看该API文档中的描述。

API数据格式

返回数据格式

JSON格式

{
  "name":"中国",
    "province":[{
  "name":"黑龙江",
    "cities":{"city":["哈尔滨","大庆"]}
  },{
    "name":"广东
    "cities":{"city":["广州","深圳","珠海"]}
  }]
}

XML格式

<?xml version="1.0" encoding="utf-8"?>
<country>
  <name>中国</name>
    <province>
      <name>黑龙江</name>
      <citys>
        <city>哈尔滨</city>
        <city>大庆</city>
      </citys>
    </province>
</country>

目前最新的API大多使用JSON数据格式。JSON（JavaSvript Object Notation）是一种轻量级的数据交换格式，采用完全独立与语言的文本格式，易于人阅读和编写，同时也易于机器解析和生成，是一种理想的数据交换语言。

JSON数据格式表示方法

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

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

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

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

API 身份验证级签名认证

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

可以通过 APPCODE 的方式，实现到被调用接口的身份认证，获取访问相关 API 的调用权限。
使用方法：
请求Header中添加的Authorization字段；
配置Authorization字段的值位 "APPCODE + 半角空格 + APPCODE值"
格式：
Authorization:APPCODE APP Code值
示例：
Authorization:APPCODE 3F2504E04F8911D39A0C0305E82C3301

API 签名认证（AppKey & AppSecret）

AppKey 和 AppSecret 相当于当前账户的另一套账号和密码机制。在云市场购买API之后，就可以在控制台找到对应的AppKey 和 AppSecret
具体的签名认证方法请参见请求头部字段以及请求签名说明文档https://www.yunshangmc.com)

API