API接口入门（一）：读懂API接口文档
本文目录：
- API接口是什么？
- 为什么我们需要API接口？
- API接口的核心
一、API接口是什么？
我们来以一个常见的数学公式理解API，比如y=x+2，当x=2的时候，y=4，对么？
那此时，我们把y=x+2称为接口，x=2称为参数，y=4称为返回结果，那这个接口的功能就是能把我们输入的数加上2（注意：这里你可以发现接口自身是带有逻辑的）。
类比地，我们来理解一个常见的场景，比如现在有一个可以把经纬度转化为城市的接口，那当我输入经度是55°，纬度是88°的时候，接口通过自己的逻辑运算，返回结果告诉我：杭州市。
这样你就可以清晰地了解百度百科的官方解释了，接口就是预先定义的函数逻辑，他是供其他系统请求，然后返回结果的一个东西。
二、为什么我们需要API接口？
背景：我们的业务系统涉及多方多面，如果要一个公司或者一个系统把所有业务都做完，那未免工作量太大了吧？并且如果其他系统或公司有更好的运算逻辑，那我们在设计功能的时候可以考虑利用接口进行开发。
核心需求：利用现有接口可以降低开发成本，缩短开发成本。
举个例子：比如我是打车的APP，现在我需要在我的页面上展现地图的功能，对于我司而言，新做地图功能未免成本过高，那我们可以在高德开放平台或者百度地图的开放平台，找到地图API，这样的话我们只需要购买高德的服务，部署调用高德地图API，这样就可以快速在我们页面上线地图功能了。
三、API接口的核心
对于小白而言，初看API文档可能是一头雾水的——从哪里看，怎么看，看什么是摆在面前的问题。
其实对于产品经理而言，我们应该更关注这个公司可以提供什么样的API接口服务，比如我知道高德可以提供地图API，规划路线的API，这样的话在我们设计功能和工作中就可以想到调用他们的服务或者参考。
所以产品小白们看不懂也不用过于担心，未来工作中你也会更深入了解清楚，因为看懂并不复杂，以下是API接口的核心点，所有的说明文档离不开这5个核心点。
以下说明均以微信开放平台为例说明，文末有各开放平台的地址，大家有空可以去学习。好了，事不宜迟，现在我们来建立一个场景。
我们现在有一个APP，需要用户在购买的时候调起微信支付的API，完成购买。请各位自动进入这个场景，把自己当作一位产品经理。
1. 接口地址
现在Now，用户点击付款，我们需要告诉微信，我们要调起你们的收银台啦！但，去哪里告诉呢？这就需要接口地址了，也就相当于向微信的这条链接传输指定的数据。
一个链接地址不是我们理解的一个页面，你可以理解是一个电话号码，小白们要改变这个观念。
此时我们可以看到接口文档告诉我们链接是如下这条，那我们现在已经拨通微信的电话了。
2. 请求参数（报文）
我们现在需要告诉微信，你想调用收银台对吧。那我们需要写下来，此时生成的叫做报文，也就是你想告诉这个接口的内容是什么？相当于前文函数的输入x=2。
一般来说，报文的格式和内容都是按接口文档规定的。如下文就是微信开放平台对调起收银台的报文要求。
我们先来看前2个参数，你现在跟微信在对话，是不是应该先告诉微信，你是谁？这里微信的文档告诉你应该要用应用ID+商户号来确定你的身份，什么意思呢？
比如你是A商户，下面有a，b，c三个APP，所以微信要知道你是哪个商家，下面的哪个APP要用收银台。这是非常重要的，微信后面要把收到的钱打到对应的账户以及统计数据等。
那我们就在报文里面写下这两句话：
- <appid>wx2421b1c4370ec43b</appid>（我的应用ID是wx2421…….）
- <mch_id>10000100</mch_id>（我的商户号是10000…….）
好了，现在微信知道你是谁了，那你要告诉微信，你需要微信支付帮你收多少钱对吧？这里定义了货币类型和总金额，也就是收什么货币，收多少钱。
这里你看，货币类型的必填写了否，也就是说你也可以不告诉微信支付货币类型是什么，因为他在后面备注了默认是人民币。
好的，那我们写下两段报文
- <free_type>CNY</ free_type >（我要收人民币）
- <total_fee>1</total_fee>（我要收1元）
好了，现在微信知道你是谁，也知道要收多少钱了，那接下来微信支付要把收钱结果告诉你呀，因为你得知道用户是成功支付了才能继续发货，服务啊等等的。所以这里我们用到通知地址，就是告诉微信，等下完事了他去哪里告诉你支付结果。那我们把地址写好：
<notify_url>http://wxpay.wxutil.com/pub_v2/pay/notify.v2.php</notify_url>
3. 返回结果
刚刚微信支付已经去收款了，现在他要在我们留下的通知地址中，告诉我们结果了。结果无非是两种：成功收款？收款不成功？
（1）成功
很顺利，现在用户成功付钱了，并且微信也把成功的消息告诉我们了，并且他还把用户支付的一些信息也告诉我们。
那这里就是微信支付成功收款后告诉我们的信息。
应用APPID，商户号：告诉你我成功扣款的是哪家商户的哪个APPID的交易。
业务结果：成功或失败
（2）失败
在产品设计的时候，我们往往很关注失败的情况，当收款失败的时候，微信同时会告诉你失败的原因，如下图很好理解，失败的原因有很多很多种，我们在设计的时候往往要分析每种失败的原因，为每个失败的原因设计页面和用户提示，以确保用户能理解。
以上就是API接口基本运作模式的理解，下面我将继续更新API接口的一些更为深入和细节的关键元素，如请求方式/签名/加解密等等。
可供参考的开放平台网站
微信支付：https://pay.weixin.qq.com/wiki/doc/api/index.html
高德平台开放平台：https://lbs.amap.com/
API接口入门（二）：API接口的签名验签和加解密原理
本文目录：
- API接口为什么要签名加密？
- API接口如何加密？
一、API接口为什么要签名加密？
想象一个场景：一位许久不见的好兄弟，突然在微信里面跟你说“兄弟，借我1万应急呗”，你会怎么反应？
我想大部分人马上的反应就是：是不是被盗号了？他是本人吗？
实际上这是我们日常生活中常见的通讯行为，系统间调用API和传输数据的过程无异于你和朋友间的微信沟通，所有处于开放环境的数据传输都是可以被截取，甚至被篡改的。因而数据传输存在着极大的危险，所以必须加密。
加密核心解决两个问题：
- 你是本人吗？（签名验签）
- 你传过来的信息是对的吗？（加密解密）
二、API接口如何签名验签和加密解密？
古代人写信通过邮差传信，路途遥远，他们为了避免重要的内容被发现，决定用密文来写信，比如我想表达“八百标兵上北坡”，我写成800north，并且收件人也知道怎么阅读这份信息，即使路上的人截取偷看了，也看不懂你们在说的什么意思。同时我在文末签上我的字迹，在盒子里放上我的信物（比如一片羽毛等等），这样收件人也就知道这份信是我寄出的了。
这被称为“对称性密码”，也就是加密的人用A方式加密，解密的人用A方式解密，有什么缺点呢？
如果你经常传输，这就很容易被发现了密码规律，比如我很快就知道你寄信都会带上一片羽毛，那我以后也可以搞一片羽毛来冒充你了。加上，如果我要给很多人寄信，我就要跟每个人告诉我的加密方式，说不准有一个卧底就把你的加密方式出卖了。
因为互联网传输的对接方数量和频率非常高，显然搞个对称性密码是不安全的。于是，基于对称性密码延伸出“非对称密码”的概念。
1. 公私钥——签名验签及加解密原理
通俗的解释：A要给B发信息，B先把一个箱子给A，A收到之后把信放进箱子，然后上锁，上锁了之后A自己也打不开，取不出来了，因为钥匙在B的手里，这样即使路上被截取了，别人也打不开箱子看里面的信息，最后B就能安全地收到A发的信了，并且信息没有泄露。
现在我们以一个单向的A发信息给B的场景进行深入了解公私钥工作原理。
- 发送者和接收者都有2套加解密的方法，而且他们把其中一套加密方法a和解密方法b都公开（虚线标黑）；
- 这里提到的加解密，因为密码学过于深奥，无法解释。大家需默认加密方法是不能反推出解密方法的，解密方法是不能反推出加密方法的。a加密就必须a解密，b加密就必须b解密；
- 现在A需要向B发送一条信息，因为信息的内容很重要，他就用接收者B的加密方法c进行加密，这样只有B自己的解密方法c才能解开，任何人获取了都解开不了，包括A自己也解不开；
- 在A向B发送信息的同时，需要带上自己的签名，这个时候A用自己才知道的加密方法b进行加密，因为任何人都知道解密方法b，所以任何人都可以看到A的签字，也就是任何人都知道这条是A发出来的信息，但因为签名不是不能公开的信息，所以被解密了也没有关系。
总结：
（1）签名会被任何人获取，但因为签名内容不涉及核心内容，被获取破解是OK的。
（2）重要内容只能接收方解密，任何人获取了都无法解密。
（3）接收者B只有验证签名者是A的信息，才会执行接下来的程序。阿猫阿狗发来的信息不予执行。
捣局者C可能的情况：
（1）他获取到这条信息是A发出的，但看不明白加密的内容。
（2）他可以也用接受者B的加密方法c向接收者B发信息，但他无法冒充发送者A的签名，所以B不会接受C的请求。
（2）公私钥的非对称加密+session key对称加密
2. 公私钥的非对称加密+session key对称加密
上一小节解释的公私钥加密是标准和安全的，但因为这类非对称加密对系统运算的需求比较大，在保证安全的前提下，还是尽量希望提升程序响应的时效。所以目前主流应用的另一种加密方式是公私钥的非对称加密+session key对称加密。
- 当A向B发送信息的时候，不需要用到B的公私钥。
- A用自己的加密方法b加密签名和一条空信息，因为信息无关重要，被破解了也没关系，B利用解密方法b验证了是A发来的信息。
- 这个时候，接收者B用发送者A的加密方法a，加密一个有时效的加密方法给A（相当于告诉A，这2个小时，我们用这个暗号进行沟通），因为只有A有解密方法，所以别人获取了也不能知道session key是什么。
- A接收到session key了以后，A用这种有时效的加密函数发送重要信息，签名仍用加密方法b加密，B用同样一个加密函数解密（实际上变成了对称加密，大家都用同样的方式加解密）
- 2小时后，再重复第2步，更新加密方法。
3. 总结
（1）当B向A发出临时有效的加密方法之后，通讯的过程变为了对称加密；
（2）这类加密方式的核心是时效性，必须在短时间内更新，否则固定的规律容易被获取破解。
捣局者C可能的情况：
（1）他获取到B发出的session key的加密文件，无法破解session key是什么。因为解密方法在A手上；
（2）通过各种手段，C破解出session key的加解密方法，但因为时效已到，session key更新，C徒劳无功；
（3）C在时效内破解出session key，但无法冒充A的签名。
以上是2种常见的加解密方式，每个开放平台会在概述中最开始介绍API调用的安全加解密方法，这是每个对接过程中必须的准备流程，如微信企业平台在概述中就已介绍利用第2种方法（企业微信命名为access_token）进行加解密传输。
三、最后
以上就是API签名验签和加解密的基本原理，接下来我会继续更新API的请求方式等问题，同时以企业微信，微信开放平台等大型开放平台的业务解释各平台支持的现有功能。
API接口入门（三）：用户授权流程原理
1. 应用场景
我们每个人都遇到过授权登录的环节，授权登录的应用无孔不入，可能你是在授权应用权限，或是授权账户登录，或是授权个人信息。
我们常见的应用场景一般有以下：
- 新安装应用：授权获取存储空间，设备信息等（手机原生弹窗）
- 支付宝授权登录淘宝：授权使用支付账户登录淘宝APP（淘宝原生页面）
- 微信打开美团外卖：授权获取你的头像和地理位置（微信原生弹窗）
因而授权登录是应用间交互的重要且广泛的步骤，深入了解过其中的原理很有必要。
2. 授权登录是什么？
以美团外卖授权获取你的头像和地理位置为例：
- 头像和地理位置属于你的个人信息，如需要传输，必须经得本人的同意，法律不允许默认传输。
- 授权登录是经得资源所有者（亦即是用户）同意，服务提供商（亦即是微信，他为你提供授权服务）提供授权服务和应用方（他来使用你的授权）使用授权的过程。
字面意思就是如下图流程：
值得关注的是第3步和第4步：当你在授权的过程中，实则是你和微信的直接交互，与美团外卖小程序无关。
亦即是：你是跟微信同意授权，也是微信接收到你的“同意”的指令，即使在网站用微信登录也是如此，如豆瓣登录，需要微信扫描二维码，确保授权动作保留和发生在微信自己的环境内。
3. 授权登录的模式
那么从形式来说，授权登录可以分为静默授权和手动授权两种模式：
- 静默授权：一般是用于获取一些类似于用户ID的信息，比如每个用户在微信的ID被称为openid，这种ID只是用户的唯一身份认证（相当于编号），不包含个人信息，应用获取openid并不能分析出你的手机号和身份证号这些个人信息。显然，很多用户都不知道openid是什么，总不能弹个弹窗问用户“你是否同意传输openid”吧。因而这类传输，用户是无感的，用户只需访问了某个页面，后台会向微信请求拿到你的openid。
- 手动授权：这种亦即是我们上文提到的用户场景，这类型场景需要获取的信息是你的个人信息，比如头像，昵称，手机号和地址等等。这些个人信息是必须经过用户手动点击同意的。
4. OAuth2原理及剖析
以上第2点是授权的基本简化，本节是更重点介绍OAuth2的系统链路流程（无论是静默或是手动，系统链路一致，只是形式的区分）。目前市面上涉及授权，权限申请的业务均通过OAuth2的方法进行设计。
OAuth2具体可以分为以下四种：
- 授权码模式（authorization code）【重点】
- 简化模式（implicit）
- 密码模式（resource owner password credentials）
- 客户端模式（client credentials）
4.1 授权码模式
其中最重要的就是第一种授权码模式，接下来我以企业微信授权码方法做解析，其流程图非常清晰。
例子讲解：
场景：该身份授权是用户在企业微信使用第三方应用时拉起授权页面的流程。类似于你在微信打开饿了么小程序。
系统交互的步骤：
- 用户在企业微信打开一个A应用。此时A应用通过静默推送获取到用户的userid，发现这个用户没有头像和昵称信息在A应用的数据库。
- 此时，A应用调用企业微信的OAuth认证链接，这个链接要带上企业ID（表明应用方），权限获取范围（头像+昵称），标记本次授权的编号（state）和授权完跳转的地址，做好链接之后，向微信发送过去。
- 企业微信收到请求后，校验企业ID和授权跳转的地址是否对应。如果验证通过，企业微信会给A应用一个令牌（code），并在前端打开企业微信的授权页面（该页面由企业微信管理）。
- 用户点击授权了之后，企业微信可以利用code和state向企业微信请求用户信息API，获得用户token，最终获得指定用户信息。
- 同时用户点击授权后，企业微信关闭授权页，并跳转到A应用在第2步提供的跳转地址。
4.2 简化模式
请记住第一个模式中的第（1）步和第（2）步都需要A应用处理，简化模式就是简化了第（2）步。
以下在微信的场景仅用于举例：
- 用户点击应用入口之后，微信直接让用户是否同意授权（授权的内容和触发时间提前配置好），用户点击同意。
- 用户同意后，跳转到该应用在后台预留的地址，并且微信把访问令牌直接告诉应用。
- 应用利用访问令牌找微信获取用户信息，完成。
此处你有没有发现，前面授权的过程并不需要应用本身参与，这个就是比授权码模式简化的地方。但这种模式不支持用户令牌的更新，也就是用户第一次授权过期了之后，下一次又需要重新手动授权。
4.3 密码模式
这种模式很直接，相当于你把你微信的账户密码告诉饿了么，饿了么利用你的账户密码去获取信息。这种方式极其不安全，用户的账户信息随时会被外泄。
4.4 客户端模式
这种其实不属于授权，实则就是两个应用间直接进行信息传输，与用户无关。
5. 总结
- 授权分为静默授权和手动授权，一般出现在打开应用登录的环节，应用广泛。
- 授权的组件或页面必须在拥有数据的应用中，这样才能确保用户在授权页上同意协议，清晰看到传输的数据范围，以及确保用户亲手同意授权。
- 授权分为四个模式，其中授权码模式是应用最广泛，最重要的模式。
- 授权码模式亦即是A应用拼接企业参数向企业微信请求打开授权页面，获取用户授权码code，再利用code获得用户的token，最终获取用户信息。