把它想成一张给程序看的菜单

API 就是程序与程序之间的一份"服务约定":一方事先写好——你想用哪个功能,就按什么格式把信息传过来;我按约定的格式把结果返回给你。把它想成一张给程序看的菜单:菜单上写明了能点什么、怎么点,你照菜单下单就能拿到菜,不需要自己进厨房看菜是怎么炒的。

你在天气应用里选城市,应用就向天气服务发出一个按约定格式的请求:城市编号加日期;服务按约定返回温度、天气状况等字段。应用拿到结果后自己决定怎样展示,就不用自己收集全部气象数据。这份约定还包括参数格式、需要什么权限、出错时返回什么提示,调用方照着办就行。

一眼看懂 / 示意图

程序之间,怎样点单和拿结果

程序之间,怎样点单和拿结果旅行应用显示穿衣提醒天气服务按约定处理请求城市编号温度、天气请求与返回遵循同一套约定
  1. 01请求

    传入约定的信息

  2. 02返回

    由应用决定怎样展示

网络API示例;API也可以存在于本地软件内部。

同一份天气数据,可以出现在不同应用里

假设天气服务约定:发来城市编号,就返回温度和天气状况。旅行应用拿到这些数据,可以做成穿衣提醒;日历应用可以把它放到当天的行程旁。它们共用取数据的方式,却不用长成同一张页面,也不用各自建一套气象观测网。

这里有两层界面:屏幕上的城市按钮给人点,按钮背后的API给程序调用。菜单上写什么,就开放什么:约定里只有'查天气'这一项,调用者能做的也就只有查天气。开发者说“接入某服务的API”,通常就是按它的说明传入必要信息,处理返回结果,并把功能接进自己的应用。

接口不一定是一个网址

常见的网络API通过HTTP通信,看起来像请求一个地址。但操作系统、浏览器或软件库提供的函数,也可以是API,不一定涉及互联网。

例如浏览器让网页申请摄像头权限并读取视频,也是通过规定的接口。接口是否对公众开放,是否收费,是否需要密钥,都是另外的设计问题。

调用成功,不等于结果永远相同

服务可能限流、超时、拒绝权限不足的请求,或者升级版本改变字段。调用者需要按返回结果处理成功和失败两种情况。

缓存可以减少重复请求,但有时效要求的数据要重新请求,缓存里的旧结果要按规则更新。因此,按约定发出了请求,还要看服务是否可用、有没有权限以及返回了什么。