Skip to content

Latest commit

 

History

History
executable file
·
55 lines (30 loc) · 2.87 KB

2021-04-11-shutdown.old.api.md

File metadata and controls

executable file
·
55 lines (30 loc) · 2.87 KB
layout title tags
post
下线旧 API 的正确方式
其他

大家好。

在开始今天的介绍之前,想跟大家介绍一个定律:隐式接口定律。

image-20210411220648083

API 可以认为是我们对外承诺的开放能力,而接口中对应的字段都有相应的作用,但是使用方并不一定会按提供方提供的使用方式进行使用,而这就会造成 API 在迁移或者下线过程中并没有那么容易。

当你在工作中需要更换或者下线一个新的 API,而这个 API 能够更好的解决之前 API 提供的能力,那如何安全可靠的更换这个 API,同时不对你的调用方造成损害呢?

以下是一个可供参考的处理方式:

1、做好计划

首先先思考几个问题,你是否有对 API 的调用方做监控,如果没有则加上;监控是否显示已经没有调用方在调用了,如果是就没必要做 API 的下线计划了,直接下线即可。

另外要下线的 API 的功能是否能通过新的 API 满足,如果可以,则可直接进行相应的转换,避免下线和迁移。

如果以上情况都不是,那你就需要做一个 API 下线计划,计划需要考虑以下三个核心问题:

a、你希望调用方做哪些改动?比如更新为其他 API、使用其它替代服务等。

b、调用方需要什么时候开始迁移 API?你推荐的迁移方式已经准备就绪了吗?

c、迁移的截止时间是?

2、与调用方沟通

通过公开的方式通知你的调用方,方式可以是文档、邮件、社交网络等。另外一个就是你需要在你的 API 中声明 API 已经不推荐使用(Deprecation)了。比如 HTTP 的调用,可以在 HEADER 中加入如下字段:

image-20210412000834389

3、渐进式关闭 API

到这一步已经过了你之前声明的截止时间,而你也不需要立马将 API 进行关闭,因为可能有部分调用方错过了迁移的截止时间。而渐进式的关闭 API 只是给这些调用方最后一次迁移的机会,当然你最开始做计划的时候要考虑这部分时间。

渐进式关闭 API 的方式一般是降低 API 的一些服务能力,让调用方能够感知到。

比如在 2018 年 GitHub 采用的一种方式是先关闭 API 一小时,然后再恢复,然后彻底在两周后关闭。

2015 年 Android 通过逐步将 API 的调用时长增加到 16 秒的方式逐步关闭 API。

4、最终关闭,删除代码

到这步就完成了整体的 API 下线工作,可以完成代码删除了。

以上就是全部介绍,希望能对你有所帮助。

更多详情请查看如下链接:https://httptoolkit.tech/blog/how-to-turn-off-your-old-apis/