一、基本概念
在API的整个生命周期中,不可能是永远不变的。功能可能有变动、服务也可能有升级迭代,这个时候对外的能力入口:API自然也需要改变。
一般来说,API的变动是不可以引入兼容性问题的,也即不管做什么变动,已经在使用的用户在不改变使用方式的前提下,是必须无感知的:假如接口需要新增一些必选参数、改变url等,则必须要通过版本迭代的方法提供N+1版本的接口,在保持老接口不变的情况下,为客户提供新接口、并引导存量服务使用起新接口。
在这期间,我们就需要开始进行API的日落流程,最终将API彻底下线。
二、日落流程
日落流程主要分成三个部分:计划阶段、准备阶段,以及实施阶段,这三个阶段的注意事项我们分别接单看下。
1、计划阶段
(1)识别待下线接口,制定下线计划
在API下线前,服务需对API做梳理与识别,并制定相关下线计划:
- 下线原因
- 最近12个月的调用量说明
- 影响范围与相关评估
- 替代方案
- 正式下线时间
- 采用下线策略
- 与客户的沟通方法
(2)评审下线计划
在服务完成下线API的梳理与计划制定后,需首先在产品团队内部进行相关评审,在评审通过后,还需在三级部门API TMG进行进一步的下线合理性评审。
在完成相关评审之后,服务才可进行接下来的API下线准备工作。
2、准备阶段
(1)发布下线公告
服务需要在官方网站里发布对应的API下线公告,内容应当包含API的下线时间、下线接口、替代接口等内容。
(2)更新API参考资料
服务需在API资料文档部分,同步更新API信息与状态,说明API为废弃状态、计划下线时间,并且给出后续的替代API。
同时,应当在API文档中也增加API公告章节,便于用户获取API关键信息。
(3)增加计算机可感知API废弃告警
服务在接口的调用层面,应当在Header
中添加Deprecated
信息:
X-API-Deprecation-Date
:需提供API的具体废弃日期,在该日期后API可能会被下线删除;X-API-Deprecation-Info
:需提供访问链接,指向关于废弃API的处理方法以及后续方案;
(4)监控API使用并周期性提醒用户
在API用户完全切换到新接口之前,需要保持原有接口的稳定性与可用性,同时还需要监控API当前调用量与调用者,定期通知用户尽快完成切换。
3、实施阶段
(1)API下线实施前评审
API实施下线前提:
- API实施下线需在公告发布12个月之后,并且至少3个月之内接口无用户调用记录;
- 实施下线前需要再次经过API TMG评审;
(2)API下线实施操作
API下线需要将API从网关中删除,并将API文档、SDK、示例代码等内容全部下线。
(3)发布API下线公告
有始有终,API下线后同样要在官网发布API下线公告。
三、小结
至此,API的全生命周期就走到了结尾,崭新的API也即将诞生,这就是API的一生。