A First Look at the Deprecation of RESTful APIs: An Empirical Study

背景

在所有类型的应用程序编程接口 (API) 中，Web API 作为通过 Internet 访问软件服务的关键互连机制发挥着至关重要的作用。开发人员经常按照 REST（REpresentational State Transfer）架构风格创建 Web API。

项目中的API 元素（例如 Java 库中的类、方法和字段）弃用分析研究已经有了许多工作， 但目前在Web API 或 RESTful API 中的弃用实践还没有相关工作。

本文工作旨在研究如何在 RESTful API 中遵循已弃用-移除的协议，并描述 RESTful API 弃用实践。

主要三点挑战：

1. 首先，与非 Web API 不同的是，缺乏用于发展 RESTful API 的标准方法。 诸如如何弃用 RESTful API 和 API 元素以及如何管理 RESTful API 生命周期等问题仍未得到解答。
2. 其次，可用于研究 RESTful API 演变的资源有限，即许多 API 仅提供 API 的最新版本，而不是整个历史。
3. 最后，文档和弃用相关信息通常以定制设计的格式在 API 的官方网站上提供。

方法设计

数据分析流程

APIs.guru 是最大的机器可读的 Web API 配置文件目录，它随着 Web API [10] 的发展而不断更新。
作者选取了 APIs.guru 上列出的 1,368 个 RESTful API 中的 2,224 个版本的 API。

数据集

RADA：RESTful API Deprecation Analyzer

1. 如果可选的布尔类型字段“deprecated”设置为“true”，则 API 元素被弃用。
2. 如果元素的描述（例如，在“summary”或“description”字段中）包含至少一个弃用关键字，则弃用 API 元素。
3. 如果 InfoObject 内的可选字符串类型字段“description”的值包含至少一个弃用关键字，则完全弃用 API 版本。

RQ1-Findings：87.3% 的引入重大更改的 RESTful API 版本在之前的版本中没有提供任何弃用信息。 在每个 API 和组织中，都会观察到各种弃用行为，即，一些版本遵循 deprecated - removed 协议，而另一些则不遵循。 通过中断更改对操作影响更大的版本更有可能在以前的版本中提及与弃用相关的信息。

RQ2-Findings：平均而言，目标 RESTFul API 中 46% 的操作与弃用相关。 与弃用相关的操作的比例因 API 而异：219 个目标 API 中的 71 个中的所有操作都受到弃用 API 元素的影响，而 102 个 API 的 API 操作影响不到 25%。 GET 操作更有可能与弃用相关。 大多数与弃用相关的操作 (46%) 都弃用了请求参数。

RQ3-Findings: 在研究的 219 个（33.3%）个 RESTful API 中，有 73 个没有提供任何替换消息。 只有 45% 的研究 API 为所有与弃用相关的操作提供替换消息，与 Java 和 C# API 相比要低得多（文献 [7] 中分别为 66.7% 和 77.8%）。 很少提供其他类型的弃用信息，例如移除时间，例如，只有 5% 的弃用相关 API 提及移除时间。

RQ4-Findings: 只有三个被研究的 API 采用了主动通信通道，即 API 使用者在使用与弃用相关的操作时会收到警告。 大部分是以文档说明的形式，少数通过社区讨论形式。