Abstract

摘要——代表性状态转移（REST）被认为是一种标准的软件架构风格，用于构建可以在互联网上集成软件系统的 Web API。 但是，在连接系统时，RESTful API 在引入重大更改时也可能会破坏依赖于其服务的依赖应用程序，例如，不再支持旧版本的 API。 为了及时警告开发人员，从而防止对下游应用程序产生严重影响，应遵循弃用-移除模型，还应列出与弃用相关的信息，例如替代方法。 虽然 API 弃用分析作为一个主题并不新鲜，但大多数现有工作都集中在非 Web API，例如 Java 和 Android 提供的 API。 为了调查 RESTful API 弃用，我们提出了一个称为 RADA（RESTful API 弃用分析器）的框架。 RADA 能够自动识别已弃用的 API 元素并从 OpenAPI 规范分析受影响的操作，该规范是用于描述 RESTful Web 服务的机器可读配置文件。 我们将 RADA 应用于从最大的 OpenAPI 规范目录 APIs.guru 收集的 1,368 个 RESTful API 的 2,224 个 OpenAPI 规范。 基于 RADA 挖掘的数据，我们进行了一项实证研究，以调查在 RESTful API 中如何遵循 deprecatedremoved 协议并描述 RESTful API 弃用的实践。 我们的研究结果揭示了现有 RESTful API 中与弃用相关的几个严重问题。 我们的 RADA 实施和详细的经验结果可公开用于未来的智能工具，这些工具可以自动识别和迁移客户端代码中已弃用的 RESTful API 操作的使用。
索引词——API 弃用、RESTful API、OpenAPI 规范、Web API、Web API 的演变

I. INTRODUCTION

在所有类型的应用程序编程接口 (API) 中，Web API 作为通过 Internet 访问软件服务的关键互连机制发挥着至关重要的作用。 如今，Web API 负责连接软件系统、数据和算法，通过简化对信息和功能的访问来创建大型软件生态系统 [1]。 根据全球最大的 Web API 目录 ProgrammableWeb，在过去十年中，Web API 的数量从 2010 年的不到 2,000 个增长到 2020 年初的 23,000 多个，增长了 1,000%。

开发人员经常按照 REST（REpresentational State Transfer）架构风格创建 Web API，称为 RESTful API [2]。 理想情况下，RESTful API 中定义的函数（HTTP 请求）不应更改，因此API 提供者和消费者可以在不影响对方的情况下独立发展他们的服务和软件。 然而，实际上，Web API 通常不是静态的，甚至比添加新功能和修复安全漏洞的 Java API 更容易更改 [3]。 与非 Web API（即不需要网络连接的 API）相比，不断发展的 Web API 对利益相关者提出了独特的挑战，因为它通常不受 API 使用者的控制。 例如，非 Web API 使用者始终可以使用库的本地副本（即旧版本）。 但是，如果不再支持所使用的服务（例如，服务被关闭），Web API 消费者必须修改客户端应用程序。

理想情况下，API 元素（例如 Java 库中的类、方法和字段）在被删除或修改之前应该被注释为已弃用。 还应提供诸如替换消息（例如，使用另一个 API 元素）之类的信息，以支持开发人员调整客户端应用程序。 不幸的是，正如先前的研究 [4, 5] 所揭示的，这种不推荐使用的协议并不总是被遵循，这给 API 维护者和消费者带来了软件维护问题。 然而，尽管越来越多地关注非 Web API 中的 API 弃用 [4, 6, 7]，但尚未研究 Web API 或 RESTful API 中的弃用实践。

我们的工作旨在研究如何在 RESTful API 中遵循已弃用-移除的协议，并描述 RESTful API 弃用实践。 但是，由于三个主要原因，分析 RESTful API 弃用具有挑战性。

1. 首先，与非 Web API 不同的是，缺乏用于发展 RESTful API 的标准方法。 诸如如何弃用 RESTful API 和 API 元素以及如何管理 RESTful API 生命周期等问题仍未得到解答。 负责互联网设计的社区互联网工程任务组 (IETF) 仍在研究两个新的与弃用相关的 HTTP 标头，这将在很大程度上有助于 Web API 弃用的标准化 [8, 9]。
2. 其次，可用于研究 RESTful API 演变的资源有限，即许多 API 仅提供 API 的最新版本，而不是整个历史。
3. 最后，文档和弃用相关信息通常以定制设计的格式在 API 的官方网站上提供。

为了实现我们的目标，我们对 APIs.guru 上列出的 1,368 个 RESTful API 中的 2,224 个版本的 API 进行了实证研究。 我们的 RESTful API 集包括流行的 Web API，例如 Gmail、Youtube、Amazon Elastic Compute Cloud (EC2)、Instagram、Kubernetes 和 Slack。 APIs.guru 是最大的机器可读的 Web API 配置文件目录，它随着 Web API [10] 的发展而不断更新。 从 APIs.guru 收集的 API 配置文件采用 OpenAPI 规范格式，这是 RESTful API [11] 的标准语言无关接口。 OpenAPI 规范允许人类和计算机在无需访问其源代码、文档或网络流量检查的情况下发现和理解 RESTful API 背后的服务功能。 此外，OpenAPI 规范解决了定制 API 文档带来的挑战，并使大规模探索 RESTful API 成为可能。

我们调查以下研究问题来指导我们的实证研究：

• RQ1: To what extent do RESTFul APIs mention deprecation before introducing breaking changes?
• RQ2: How do API providers deprecate RESTful APIs?
• RQ3: What deprecation-related information is provided for API consumers?
• RQ4: How API consumers are informed about the deprecation in RESTful APIs?

为了回答上述研究问题，我们首先提出了一个名为 RADA 的新框架，它代表 RESTful API 弃用分析器。 RADA 可以识别给定 OpenAPI 规范中已弃用的 RESTful API 元素（例如，URI 路径、方法、请求参数、响应参数），然后总结已弃用的 API 操作及其相关的弃用相关描述。 我们将 RADA 应用于 2,224 个收集的 OpenAPI 规范并进行我们的实证研究。 我们的实证研究发现：

1. 在 251 个 RESTful API 版本中，在之前版本的基础上引入了重大更改，其中 87.3% 没有弃用之前版本中的任何操作；
2. 38% 的研究过的与弃用相关的 API 包含超过 50% 的受弃用 API 元素影响的操作，并且 65% 的受影响操作具有弃用的请求参数；
3. 45% 的研究过的与弃用相关的 API 为所有受影响的 API 操作提供替换消息；
4. 研究的 219 个与弃用相关的 RESTful API 中只有 3 个采用主动方法进行与弃用相关的通信，即在客户端代码中调用弃用的 API 操作时使用特殊的 HTTP 标头和错误代码通知开发人员

总而言之，我们在本文中做出了以下主要贡献：

• 我们设计了一个名为 RADA 的框架，该框架可以自动识别和分析受给定 OpenAPI 规范的 RESTful API 的弃用 API 元素影响的操作。
• 我们提出了一种基于启发式的方法来表征来自 OpenAPI 的详细弃用信息说明。
• 我们对 APIs.guru 中存储的 RESTful API 的弃用进行了第一次实证研究。 这项工作中包含的 Web API 的数量是现有的关于 Web API 演变的实证研究中最多的。 我们还为 RESTful API 利益相关者提供了重要的启示，以更好地促进不断发展的 Web API。
• 我们提供了一个复制包1，其中包含我们的预处理数据和 RADA 在 Python 中的实现，作为对这个主题进行更深入研究的一种手段。

II. BACKGROUND

A. RESTful API and RESTful API Deprecation

B. OpenAPI Specification

III. EMPIRICAL STUDY SETUP

A. Data Collection

我们从 APIs.guru（Web API 的维基百科）收集了目标 RESTful API 用于我们的实证研究。 APIs.guru 于 2016 年推出，用于托管公开可用的 RESTful API 的机器可读文档（即 OpenAPI 2.0 和 3.0 规范）。 我们选择 APIs.guru 主要是出于三个原因：

1. 它拥有最全面和最新的 OpenAPI 规范列表，这些规范要么由公共 RESTful API 直接提供，要么由领域专家从官方 API 文档中转移而来；
2. 它将他们收集的 RESTful API 的历史 OpenAPI 规范存储在 GitHub 上，从而使分析 RESTful API 演变成为可能；
3. 在之前关于 Web API 的研究中，它被认为是 RESTful API 文档的代理 [13, 14]。

在下文中，我们描述了我们如何收集特定的数据片段，我们依靠这些数据片段来回答第 1 节中提出的四个 RQ。图 2 概述了数据收集过程。

Step 1. Collect and clean OpenAPI specifications.

Step 2. Collect multi-version APIs.

Step 3. Identify deprecation-related API versions using RADA.

Step 4. Collect the latest deprecation-related APIs.

B. RADA: RESTful API Deprecation Analyzer

RADA 将 OpenAPI 规范作为输入，然后输出一组 API 操作及其相关的弃用相关信息。 如果 API 操作中的任何 API 元素被弃用，该 API 操作将被标记为与弃用相关的 API 操作。 RADA 的设计基于我们的观察，即 RESTful API 提供者通常使用可选的 deprecated 字段或 deprecation 关键字，即任何包含前缀 deprecat（例如 deprecated、deprecation 和 deprecating）的词来指定已弃用的 API 元素。 RADA 使用以下三个弃用标准来识别弃用的 API 元素和版本：

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

算法 1 显示了 RADA 的主要过程。 它读取一个 API 规范 s 作为输入，并输出一个映射结果，其中包含每个 API 操作 opNm 及其相关的七条弃用相关信息，即 isDpr、hasOp、hasResp、asReq、opText、respText 和 reqText。
isDpr ： opNm 是否与弃用相关 boolean
hasOp ： opNm 是否具有弃用的操作 boolean
hasResp ： opNm 是否具有弃用的响应参数 boolean
asReq：opNm 是否具有弃用的请求参数 boolean
opText：在弃用操作的描述/摘要中包含弃用关键字的文本 string
respText ：和 在弃用操作的响应参数包含弃用关键字的文本 string
reqText ：在弃用操作的请求参数中包含弃用关键字的文本 string

（第 3 行）RADA 解析输入规范 s 并根据弃用标准 3确定整个 API 版本是否被弃用。
（第 4 行） 然后它从 s 中的全局部分检索通用数据结构 globalDef 的定义。
（第 9 行） 这个变量是在每个 API 操作中生成完整的请求对象和响应对象所必需的。
（第 5-14 行）接下来，RADA 通过访问每个路径对象内的每个方法对象来处理每个 API 操作。
（第 7 行）opNm 由每个访问的方法及其外部路径对象确定。
（第 5-8 行）对于每个操作，RADA 确定操作本身是否已被弃用
（第 8 行）并根据弃用标准 1 和 2 提取与弃用相关的文本。
（第 10 - 11, 13 - 14 行）然后将该过程重复应用于每个请求和响应对象。
（第 16-17 行）从 operation、reqObj 和 respObj 收集所有与弃用相关的信息后，RADA 会将 opNm 的弃用相关变量 isDpr 设置为 true，如果opNm 包含至少一个已弃用的元素。 对于非弃用相关的 API 操作，isDpr、hasOp、hasResp、hasReq 设置为 false，而 txtOp、txtResp 和 txtReq 设置为 null。

Evaluating. RADA 建立在一组基于启发式关键字的规则之上。 因此，它可能会遭受一些误报和误报的情况。 误报案例表示未弃用的 API 元素，这些元素被标识为已弃用，因为它包含至少一个弃用关键字。 假阴性案例代表 RADA 遗漏的已弃用 API 元素，因为它没有提及任何弃用关键字。 为了进一步将这种威胁迁移到有效性，我们随机抽样了 50 个 API 版本，其中包含 3,444 个 API 操作。 我们仔细阅读了与每个采样 API 操作相关的定义，并手动确定该操作是否已弃用。 然后，我们将 RADA 返回的标签与我们手动创建的标签进行比较。 我们的评估结果表明，在 API 版本级别，RADA 达到了 100% 的准确度，即捕获了包含至少一个弃用元素的所有 API 版本，并且所有捕获的 API 版本确实包含弃用元素。 在 API 操作级别，RADA 实现了 94% 的精度和 100% 的召回率。

IV. RESULTS AND IMPLICATIONS

A.RQ1

Motivation. API 提供者可能不遵循弃用-删除协议，即，他们直接引入破坏性更改，而没有为 API 消费者留下足够的过渡时间。 在本文中，重大更改是指更新或删除 API 元素，包括操作、请求参数和响应参数。

Approach. 为了回答 RQ1，我们从存储在 APIs-guru 中的多个版本的多版本 Web API 开始。 相同 API 的多个版本的普遍存在使我们能够跟踪 API 的演变，并了解在演变过程中引入了哪些重大变化。 更具体地说，在第 III-A 节中，我们观察到 1,368 个目标 RESTful API 中只有 16% 包含与弃用相关的版本。 但这并不意味着剩下的 1,149 个 API 不遵循已弃用-删除的协议。 因为许多目标 API 可能只有一个发布版本，或者不需要弃用任何 API 元素，因为它们始终保证跨版本的向后兼容性。 因此，RQ1 以多版本 API 为目标，这些 API 与以前的版本相比引入了重大更改，即它们是遵循已弃用-删除协议所需的 API。

对于多版本 API，我们首先将多个版本的规范按照发布日期或版本 id 排序升序，例如 {V1, V2, V3}。 然后从 API 的第二个收集版本（即 V2）开始，我们通过将其规范与之前版本的规范（即（V2，V1）和（V3，V2）进行比较，提取出引入的重大更改。 我们采用了一个流行的 OpenAPI 规范差异工具，名为 SwaggerDiff [15]，以执行两个连续规范之间的比较。 由于 SwaggerDiff 仅支持 OpenAPI 2.0，我们使用名为 api-spec-converter [16] 的工具将 78 个 OpenAPI 3.0 规范转换为 2.0，以执行两个连续规范之间的比较并识别重大更改。

接下来，我们将 RADA 应用于相关 API 规范，以在引入重大更改之前确定它们是否与弃用相关（即提及与弃用相关的信息）。 例如，如果我们确定 V2 引入了对先前版本 V1 的重大更改，我们将在 V1 上应用 RADA 来确定 V1 是否有任何已弃用的 API 元素。 请注意，我们没有检查已弃用的 API 元素是否与重大更改匹配，因为我们专注于了解一个 API 版本是否采用弃用实践，而不是查找 API 提供者未能标记为已弃用的单个 API 元素。 因此，我们研究的结果将是遵循已弃用-删除协议的 API 数量的上限。 在实践中，完全遵循协议的 API 的数量，即注释每个弃用的 API 元素，甚至会比我们报告的要少。

Results. 我们对来自 212 个多版本 API 的 1,068 个规范应用了调整后的 SwaggerDiff。 未能解析两个规范。 最后，我们确定了 251 个在之前版本的基础上引入了重大更改的版本。 其中，只有 32 个版本（12.7%），其之前的 API 版本与弃用相关，而其余 219 个（87.3%）的 API 版本在进行更改之前未指定任何与弃用相关的信息。 然后，我们进一步研究了每个 API 如何处理已弃用的已删除协议。 我们在 API 级别定义了三种类型的行为：

1. always-follow，对于所有引入重大更改的版本，其先前版本与弃用相关；
2. always-not-follow，对于所有引入重大变更的版本，之前的版本不提供任何弃用信息；
3. mixed，一些版本跟随而有些没有。

我们发现，在 133 个考虑的 API 中，只有 16 个始终遵循协议，4 个具有混合行为，其余 113 个（84.3%）始终不遵循。 我们在组织层面进行了类似的研究。 这 133 个 API 来自六个组织，即 Azure (102)、Google (17)、Adyen (6)、AWS (5)、Microsoft (2) 和 Windows (1)。 对于每个组织，我们计算了组织下三种弃用行为类型中的每一种的 API 数量，并将结果绘制在图 3 中。

我们可以观察到，即使在同一个组织内，弃用行为也可能因 API 不同而不同。 Google 在所有被考虑的组织中表现最好，其 69% (9/13) 的 API 始终遵循已弃用-删除的协议。 这四个混合行为 API 都来自 Azure。 由于上述结果表明缺乏关于遵循 RESTful API 中弃用-删除协议的标准策略，我们还对不弃用重大更改的潜在原因进行了初步调查。 我们假设，如果在一个版本中只有少数操作受到重大更改的影响，开发人员可能会选择忽略已弃用-删除的协议，因为他们可能认为很少的更改不会影响许多 API 使用者。 为了验证这一假设，我们比较了遵循弃用协议的 API 版本和不遵循的 API 版本之间受移除/修改的 API 元素影响的 API 操作数量。 我们观察到，与遵循协议的版本相比，确实不遵循弃用协议的 API 版本通过中断更改对操作的影响要小得多。 事实上，73.5% (161/219) 的 API 版本中没有遵循弃用，只有不到 10 个操作受到重大更改的影响。 对于遵循弃用删除协议的 API 版本，相同的比率为 47% (15/32)。 遵循和不遵循弃用协议的 API 中断更改影响操作的中位数分别为 10 和 5。

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

B.RQ2

Motivation. 不存在弃用 RESTful API 的标准方法，这意味着 API 提供者将采用不同的弃用策略。 在第二个研究问题中，我们对 RESTful API 的弃用模式进行了分类。 这些知识将帮助 API 提供者了解实践并帮助 API 消费者评估采用特定弃用相关版本的潜在风险。

Approach. 我们从三个方面来描述 RESTful API 中的弃用模式，即受影响的 API 操作的普遍性、方法类型和弃用的来源。 RQ2 针对最新的 219 个与弃用相关的版本（参考第 III 节）。 我们描述了每个考虑方面的详细方法如下。

• Prevalence: 使用 RADA 返回的输出可以直接估计弃用 API 操作的普遍性。 我们计算每个目标 API 中提供的总 API 操作数，以及被 RADA 识别为弃用的 API 操作数。 然后跨目标集计算与弃用相关的操作比率（#deprecation-related operations/#total operations）。
• Method Type: RESTful API 操作可以根据其 HTTP 方法类型进行分类。 根据 RADA 针对每个目标 API 返回的信息，我们首先计算每种方法类型的 API 操作总数，然后计算每种方法类型中弃用的操作数量和比例。
• Deprecated Source: 与弃用相关的 API 操作可能会受到弃用操作、请求参数或响应参数的影响。 根据 RADA 返回的结果，我们分别计算具有弃用操作、请求参数和响应参数的弃用相关 API 操作的比率。 请注意，一项与弃用相关的操作可能有多个弃用源。

Results. 我们发现，平均而言，每个研究的 API 中 46% 的操作与弃用相关。 然后，我们根据弃用相关操作的比率创建五组 API：(0, 25%), [25%, 50%), [50%, 75%), [75%. 100%）和 100%。 最受欢迎的组是 (0, 25%)，这意味着大多数被研究的 API 的总操作数不到 25% 受到已弃用的 API 元素的影响。 很少有 API 有超过 25% 和低于 100% 的弃用相关操作：组 [25%, 50%), [50%, 75%), [75%. 100%) 分别包含 25、18 和 3 个 API。 令人惊讶的是，我们还发现 219 个研究的 API 中有 71 个的所有操作都受到已弃用的 API 元素的影响。 然后我们手动调查该组中的 API 并发现：

1. 在 info 部分中指定的四个 API 已弃用整个 API 版本，建议 API 使用者迁移到最新版本的 API；
2. 该组中的许多 API 只有很少的操作，因此它们更容易同时受到影响；
3. 不推荐使用/交叉路径对象内的一些共享（主要是查询）参数，它们会影响可以与参数一起调用的所有操作。

图 4 根据所研究的 219 个 API 中与弃用相关的操作比率显示了不同 HTTP 方法的小提琴图。 我们发现 GET 操作更可能与弃用相关，其次是 POST 操作。 具体来说，219 个 API 中有 71 个包含与弃用相关的 GET 操作，在 65 个 API 中，它们的所有 GET 操作都受到弃用的 API 元素的影响。 在每个目标 API 中，平均 41%、35%、25%、20% 和 17% 的 GET、POST、PUT、DELETE 和 PATCH 操作与弃用相关。 GET 和 POST 操作受影响 API 操作率的中位数分别为 18% 和 12%，而其他三种操作的中位数为 0%。

图 5 显示了三个弃用源的小提琴图，基于它们在每个目标 API 中与弃用相关的操作比率。 我们可以观察到，大多数与弃用相关的操作都受到弃用的请求参数的影响，其次是弃用的响应参数。 较少数量的操作直接弃用了操作。 平均而言，46%、42% 和 24% 的弃用相关 API 操作包含弃用的请求参数、响应参数和操作，中位数分别为 40%、21% 和 0%。

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

C.RQ3

Motivation. API 提供者应始终提供明确的弃用相关信息，包括替换消息（即，可以使用哪个操作来实现相同的功能）、何时删除该操作等。不充分的弃用信息会使 API 使用者无法规划他们应该做什么 当正在使用的 API 被弃用时，请务必保留现有功能。 但是，不知道为 RESTful API 提供了多大程度的弃用信息。 因此，在此 RQ 中，我们调查了 OpenAPI 规范中提供的弃用信息的详细信息。

Approach. 我们对 OpenAPI 规范中相关字段的文本描述进行了半自动分析，并描述了提供了哪些类型的弃用信息。 特别是，我们分析了 RADA 检测到的 219 个与弃用相关的 Web API 的最新版本。 RADA 总共报告了 880 个文本描述（即来自 OpenAPI 规范中的“描述”或“摘要”），其中包含与弃用相关的关键字（第 III-B 节）。 检测到的 797 个文本描述来自总共 203 个 Web API。 请注意，某些 API 元素被标记为已弃用（即，弃用字段设置为 true）但不包含任何文本描述，因此我们在此 RQ 中排除了此类 API 元素。

我们按照开放式卡片分类方法 [18] 对 RESTful API 的弃用信息进行了描述和总结。 更具体地说，我们对一组随机选择的 100 个文本描述应用开放式卡片排序，并总结了总共五种类型的弃用信息。 然后我们设计了一种基于启发式的方法来自动表征剩余 697 个（即 797-100）个文本描述中的弃用信息。

下面我们将详细介绍每种类型的弃用信息（即替换消息、外部引用、解释、弃用和删除时间）以及基于启发式的方法如何自动检测它们。 具体来说，我们处理了每个文本描述（即，删除多余的空格并转换为小写）并应用以下规则来决定文本描述中是否描述了一种类型的弃用信息。

• Replacement Message. 建议使用替代品来替换弃用的 API 元素。 推荐替代参数的一个示例是“不推荐使用以支持所需的包大小字节”。 我们总结了用于表示替换的常用关键字，并利用它们来检测一个文本描述是否列出了替换，即“deprecated by”, “recommend”, “use ”, “in favor of”, “replaced by”, “instead”, “merged into”, “see and preferred.
• External Reference. API 提供者可能会在外部文档中包含详细的弃用信息，例如“this group version of deployment is deprecated by apps/v1/deployment. see the release notes for more information”。 我们总结了外部文档的常见类型，并将它们用于检测外部引用，即“release note”、“changelog”、“migration”。
• Explanation. API 提供商可能会解释弃用背后的原因，例如“this property has been deprecated due to privacy changes”。 我们搜索关键字，即“due to”，以确定弃用的原因。
• Deprecation Time. 可以指定一个 API 元素开始弃用的时间/版本，例如“this field has been deprecated as of version 2.1”。 我们使用是否包含关键字 deprecated in 来检测弃用时间。
• Removal Time. API 提供者可能会指明一个弃用 API 元素的正式删除时间.

Evaluating 我们为本次评估抽取了 248 个文本描述的统计显着性 (95 ± 5%) 样本。 人口是 697（即 797-100）文本描述。 我们手动检查了每个文本描述，并确定它是否包含五种类型的弃用信息中的一种或多种。 然后将手动获得的地面实况与基于启发式方法的结果进行比较，以评估性能，即通过精度和召回率来衡量（表 II）。 精度显示每种类型检测到的实例中有多少是正确的（即，与真实情况一致）。 Recall 显示了可以正确检测到的真实实例的百分比。 总体而言，每个的精度和召回率都是可以接受的，除了弃用时间，召回率不高（46%）。 我们从进一步分析中排除了弃用时间。

Result.

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

D.RQ4

Motivation. 传达已弃用的 API 元素是一项重要活动，可确保 API 使用者了解可能影响其代码的已弃用元素。 在非 Web API 中，可以通过编程语言的支持轻松完成通信。 例如，从 J2SE 5.0 开始，Java 提供了一种机制来弃用 API 元素，包括类型、方法和字段，使用“@Deprecated”注释。 此注释会导致编译器在发现已弃用的 API 元素正在使用时发出警告消息。 Java 还提供了一个“@deprecated”Javadoc 标记，可以使 Javadoc 将程序元素显示为已弃用。 然而，包括 RESTful API 在内的 Web API 还没有来自 HTTP 的类似支持 [9]。 因此，在最后一个研究问题中，我们调查了 API 提供者利用哪些额外的通信渠道与 API 消费者进行通信。

Approach. 我们对 RADA（第 III 节）确定的 219 个与弃用相关的 API 的官方网站进行了人工检查，发现了两种类型的通信渠道。

第一种称为技术交流。 一个示例技术沟通渠道是 API 响应。 例如，一些 Web API 可以使用自定义 HTTP 标头（例如，Clearbit API 中的“X-API-Warn”）在客户端代码中调用已弃用的操作时向开发人员发出警告。 技术交流是主动的，类似于 Java 中的“@Deprecated”机制。

第二种是非技术交流。 非技术渠道包括 API 文档/OpenAPI 规范（即 RQ1-3 的重点）、演进相关渠道（发布说明/变更日志/更新/迁移指南）和社交媒体平台（即博客、Twitter 和 API 论坛/社区）。 我们在可能的沟通渠道（即 API 官方网站和社交媒体帐户）中搜索弃用关键字，以确定用于 API 弃用的其他沟通渠道。 因此，拥有 twitter API 帐户并不意味着 API 通过 Twitter 传达弃用信息，除非它使用 twitter 帐户提及弃用信息。 请注意，API 提供商可能会提供电子邮件订阅服务来传递弃用信息。 但是，由于我们无法访问这些电子邮件帐户，因此我们无法验证那里是否就 API 弃用进行了任何讨论。 因此，我们不包括电子邮件作为在 RQ4 中进行检查的通信渠道。

Result. 表 III 表示在所研究的 219 个 API 中如何采用不同的通信渠道来传达弃用。 请注意，由于 219 个 API 要么将 deprecated 字段设置为 true，要么在其相应的 OpenAPI 规范中指定弃用信息，因此它们都在其官方文档中指定弃用信息也就不足为奇了。 然而，除了文档之外，我们只发现 61 个 API 使用了第二个通信通道，其中大多数使用与进化相关的通信通道来进行弃用通知。 此外，只有三个 API 采用了主动技术通信通道：当在客户端代码中调用已弃用的操作时，Jira 使用自定义 HTTP 标头发送弃用通知； Kubernetes 使用 HTTP 警告标头（目前已被 HTTP [19] 弃用）； NBA Stats 使用与响应代码 404 关联的错误消息来指示已弃用的操作。 我们的结果表明，大多数关于弃用的通信都是以被动方式进行的，即 API 文档。 虽然 API 消费者可以定期检查通信渠道，但我们认为需要更积极的支持来让 API 消费者了解弃用情况。

RQ4-Findings: 只有三个被研究的 API 采用了主动通信通道，即 API 使用者在使用与弃用相关的操作时会收到警告。 除了文档之外，还利用了其他反应式沟通渠道，例如发行说明和 Twitter，但不太常见。

E.Implications

Guidelines for a clear and consistent RESTful API deprecation policy. 明确一致的 RESTful API 弃用政策指南。
Tools for automatic detection of deprecated API use in client applications. 用于自动检测客户端应用程序中已弃用的 API 使用的工具
Tools for migration support on deprecated web APIs. 在已弃用的 Web API 上提供迁移支持的工具。
Well-maintained repositories of web API artifacts. 维护良好的 Web API 工件存储库。

V. THREATS TO VALIDITY