APIMig: A Project-Level Cross-Multi-Version API Migration Framework Based on Evolution Knowledge Graph

1 Introduction

In modern software development, third-party libraries are essential for developers, facilitating specific functionalities and enhancing development efficiency for scalable applications [Mahmud et al., 2021]. As technology progresses, third-party libraries continually evolve. Consequently, developers must upgrade these libraries to access new features, fix bugs, and address security vulnerabilities, ensuring project security and compatibility [Kula et al., 2015].

However, library updates typically proceed independently of their callers, and significant changes in new library versions often introduce backward-incompatible API modifications, posing challenges to the quality assurance of upperlevel software [Yan et al., 2024]. To prevent compatibility issues arising from library updates, API migration has become a critical task for software quality assurance.

∗Corresponding author

Currently, most migration processes are performed manually by developers, who are required to consult library documentation, version release notes, and open-source community resources to understand new version features, assess their impacts, and estimate the migration effort [Kula et al., 2018]. Developers then manually identify the affected API usage within the project and perform appropriate code replacement to finalize the migration.

To automate the API migration at project-level, especially across multi-version, there are two main challenges:

Challenge 1: lack of specific library evolution knowledge across multi-version. Library maintainers typically document API differences between consecutive versions in change logs or release notes. In practical scenarios, library migrations usually involve skipping intermediate versions. However, the API change information is fragmented since only the changes between adjacent versions are provided. There is a lack of explicit and coherent API evolution knowledge across multiple versions.

Challenge 2: difficulty in identifying the chain of changes at project-level. Due to interdependencies among code elements, the code changes would propagate through the project in a chain, making it challenging to promptly identify and adjust indirectly affected code segments. Consequently, achieving automated code migration at the project level becomes highly challenging.

Traditional approaches [Fazzini et al., 2019; Xu et al., 2019; Nielsen et al., 2021; Lamothe et al., 2022; Wang and Yu, 2022] to API migration involve extracting migration instances from the current and target versions of opensource projects, applying them through pattern matching to find suitable instances. The rapid evolution of large language models (LLMs) has led to research that leverages their strong understanding and generation capabilities for code migration tasks. Existing studies [Almeida et al., 2024; Wu et al., 2024] are typically empirical-oriented, focusing on validating the feasibility of generated migration code by LLMs. Empirical studies show LLMs struggle to meet the challenges, as current models are hard to adapt to changing libraries promptly and to understand library dependencies.

To address the challenges mentioned above, we propose a project-level cross-multi-version API Migration framework (APIMig). To address the specific library evolution knowledge across multi-version (Challenge 1), we first construct an API evolution knowledge graph to capture the dynamic API changes as the version evolves and then derive the coherent cross-version API evolution knowledge by KG reasoning. To address identifying the chain of changes at project-level (Challenge 2), we design a chain exploration algorithm based on the project dependency graph, allowing us to identify the comprehensive code segments impacted by changes throughout the project. Finally, we construct prompts for the API migration requirement, guiding the LLMs to complete the API migration task by providing API evolution knowledge and the chain of changes.

The contributions of this paper are as follows:

1. Cross-version API evolution knowledge: We propose a dynamic API Evolution Knowledge Graph (APIEvoKG) and derive coherent multi-version API evolution knowledge by KG reasoning.
2. Project-level chain of changes: We propose a Chain Exploration Algorithm(CEA) based on project dependency graph to track the chain of changes and identify all code segments to be updated within the project.
3. Dataset and effectiveness: We construct a KG for the Lucene library, and the migration project pairs datasets from different major versions. The experiments demonstrate the effectiveness of our approach in project-level cross-multi-version API migration task.

2 RelatedWork

2.1 Instance-Based API MigrationMethod

The instance-based approach to project migration is predominant in existing research, focusing on deriving editing scripts from migration instances and applying them to new contexts. [Nguyen et al., 2010] used a code analysis tool to analyze modifications in API declarations and extracted API usage snippets from clients that successfully migrated. They used a pattern miner to infer adaptation patterns, aiding library version migration automatically. [Xu et al., 2019] proposed Meditor, a template-based migration method in two stages. They sourced projects using the target library from GitHub, analyzed commit histories to extract API migration edits, and generated migrated programs by matching these edits to source code templates. [Lamothe et al., 2022] proposed A3, a migration method based on the principles of mining, applying, and testing migration patterns. A3 extracted migration patterns from various sources using API name matching and data flow graph. Then, these patterns were applied to the target code to facilitate migration, and test suites were used to confirm the effectiveness of migration.

Approaches based on project-level migration instances identify potential changes by mining API migration patterns, which means that their applicability and flexibility are limited

[Bai et al., 2024]. Migration relies on programs that have successfully migrated to new library versions, which requires a large number of API usage examples. In practice, finding migration instances for each API change is often infeasible, particularly for these changes in new library versions. Moreover, the differences between versions make it difficult to establish associations between changes.

2.2 LLM-Based API MigrationMethod

LLMs have been little used in API migrations. [Almeida et al., 2024] introduced a library migration framework, evaluating different prompt types for LLM-based API migration. [Bairi et al., 2024] employed prompt engineering to integrate the migration task instructions with API modifications and contextual information. Meanwhile, [Zan et al., 2022] and [Zhou et al., 2023b] observed that LLMs frequently encounter difficulties in generalizing beyond their training data distribution. They suggested employing RetrievalAugmented Generation (RAG) to access more efficient APIs, thereby enhancing code generation capabilities. However, [Wu et al., 2024] highlighted the challenges in using RAG for version-controlled code generation, as ambiguous versionrelated queries can complicate the retrieval process [Wang et al., 2020]. Specifically, similar embeddings of version strings, such as "V2.1.3" and "1.3.2V", can hinder the accuracy of retrieval systems to distinguish version-specific features and functionalities [Zhou et al., 2023a].

In response to the practical needs of cross-version API migration, we propose the APIMig framework. We design a scalable and dynamic API evolution knowledge graph to effectively infer the coherent knowledge of multi-version API evolution. By analyzing the affected elements in the knowledge graph and employing the chain exploration algorithm, we can accurately identify the affected code that needs to be modified, thereby improving the accuracy of migration results generated by LLMs.

3 Approach

Problem Definition. The project-level API migration task across multi-version is defined as follows: Consider a third-party dependent library L, which has n versions V1, V2, V3, . . . , Vn. Given a project P to be migrated, which depends on the version Vi of L, the target is to migrate the code in P to version Vj (only considering upward migration, 1 ≤ i < j ≤ n).

Framework Overview. Figure 1 shows the framework of APIMig. APIMig focuses on facilitating project-level crossmulti-version API migration through the use of API evolution knowledge. The framework consists of three key components: 1) API Evolution Knowledge Reasoning. We built the APIEvoKG to capture the changes that occur between adjacent library versions and derive the coherent cross-version API evolution knowledge through KG reasoning. 2) Chain of Changes Exploration. We design a chain exploration algorithm to track the code segments affected by API changes through the project dependency graph. 3) LLM-based API Migration. We employ LLM to facilitate the completion of API migration using the API evolution knowledge and the identified chain of changes.

3.1 API Evolution Knowledge Reasoning

Construction of the APIEvoKG. The APIEvoKG schema was specifically designed to capture key elements of the API documentation and track evolution within those APIs.

The entities include three types: API Library (EL), API Element (Ee), and API Evolution (EEvo). The primary entityrelationship-entity triples are as follows: (EL, has element, Ee), (EL, has evolution, EEvo), (EEvo, source from, Ee), and (EEvo, target to, Ee). The "has..." relationship indicates a containment relationship between entities, "source from" indicates the Ee to be evolved, and "target to" indicates the Ee after the evolution. The EEvo entity has two key attributes: "type", which includes add, remove, and update to represent the type of API Evolution, and "scope", which denotes the evolution target (e.g., Method, Parameter).

Based on the aforementioned schema, we develop different extraction methods for types of knowledge from API documents, release notes, and change logs. We employ a keywordbased heuristic approach to extract entities (Ee) such as class and method, as well as the dependency relationship. We use a pattern-matching method to extract fine-grained Ee such as parameters. Furthermore, we use prompts to guide LLMs through a few-shot learning to extract (EEvo) and the relationship between EEvo and Ee. Furthermore, we conduct human reviews to ensure the quality of the extraction process.

API Evolution Knowledge Reasoning. In APIEvoKG, EEvo captures API evolution information between adjacent versions. During cross-version evolution, API elements often experience multiple, successive changes. Inspired by [Zhao et al., 2024], we extract evolutionary paths and infer crossversion API evolution knowledge through reasoning rules.

1) Evolutionary Path Extraction. Define ELV i as an API evolution entity in version Vi of Library L, ES as the source API element entity, ET as the target API element entity, and "type" and "scope" represent attributes of the evolution, respectively. A set of 1-hop evolutionary paths denoted as P 1 can be extracted by the following path (1) and will be appended to the API Evolutionary Path List (EPListji ).

To capture the API evolution knowledge of L from version Vi to Vj, while traversing the knowledge graph, if the API element entity in the 1-hop path of the subsequent version is included in the path in the EPListji , we extract a 2-hop evolutionary path P 2 . By repeating these operations, we continue until all change entities have been traversed, and we obtain the complete set of multi-hop evolutionary path P n (2) for evolved APIs across multi-version of library L.

2) Jointly Reasoning. We conduct joint reasoning for evolutionary paths over 2-hop, which includes reasoning about change operations and their scopes.

Using 2-hop reasoning as an example, in a 2-hop context, two changes can influence different scopes of the same element, such as modifying method parameters and altering its return value type. Therefore, we define a union operation to represent the impact of these scopes: if Scope1 = Scope2, we select Scope1; if Scope1 differs from Scope2, we take their union, indicating that changes have occurred in both scopes.

Additionally, we identify three atomic evolution types: add, remove, and update. Different atomic operations within the same scope may have varying impacts. We present the evolution reasoning rules in Figure 2, and provide an Example. In this example, we obtain evolution knowledge for the Lucene Library from version 6.0.0 to 8.0.0 in APIEvoKG, including API Evolution Entities and their related API Element Entities. For EEvo1 and EEvo2, we can respectively extract 1-hop evolution paths according path1. Since ES2 is included in P 1Evo , we can extract a 2-hop evolutionary path P 2 . The two evolution entities share the same scope, and based on rule5 of Reasoning Rules, we can derive the inference result and corresponding description. In this way, we derive the cross-version API change information for evolutionary paths in EPListji and get the valid reasoning results.

3.2 Chain of Changes Exploration

Project-Level Code Dependency Graph. We designed a heterogeneous dependency graph to represent the structure and dependencies of a project.

This graph consists of three types of nodes: 1) Structural nodes, such as the class body, which organize the code structure; 2) Statement nodes, including class declarations, method declarations, and others, which detail specific code statements; and 3) Element nodes, such as variables and parameters, which describe the components of the statements.

The graph includes three types of edges: 1) Structural edges (str), connecting Structural nodes to Statement nodes or between Statement nodes, thereby highlighting hierarchical relationships and the execution order between statements; for example, a method body contains multiple statements; 2) Dependency edges (dep), representing a forward dependency relationship based on the execution order between nodes; and 3) Reverse Dependency edges (redep), indicating a backward dependency between the current Statement node and the preceding Element node, such as the relationship between the current method call statement and its parameters.

Callsite Analysis. API migration affects a project beyond immediate call sites due to interdependencies between code elements and the impact can significantly vary based on the scope of changes. For instance, modifications to API method parameters and return types can influence different parts of the project. To illustrate this, we define the Callsite Analysis rules in Figure 3 that outlines the potential impact range of various code elements under different change scopes. In this context, we define "Callsite" as the statement where an API is invoked, "Before Callsite" as the preparatory statements preceding the API call (with redep), and "After Callsite" as the statements that utilize the return of the API call (with dep).

Chain Exploration Algorithm. We developed the Chain Exploration Algorithm (CEA) to track the chain of changes and identify all code segments that require updating throughout the entire project, as demonstrated in Algorithm 1.

Algorithm 1 Chain Exploration Algorithm

Input: Dependency Relation Graph G = (N,E), Callsite list N ∗ = {n∗0 , n∗1 , . . .}, N = {ni ∈ G} ind(ni) return the in-degree of ni getImpactNodes(gran, scope, ni) return Impact Statements Nodes Output: Callsite Block List CBL : {B0, B1, . . .} 1: while |N ∗ | > 0 do 2: ni ← argminni∈Nind(ni) 3: if ni ∈ N ∗ then 4: Nipt ← getImpactNodes(gran, scope, ni) 5: BCS,ACS ← [], [] 6: for each nj ∈ Nipt do 7: if e(ni, nj).type == dep then 8: ACS .append(nj ) 9: end if 10: if e(ni, nj).type == redep then 11: BCS .append(nj ) 12: end if 13: ind[nj ] ← ind[nj ] - 1 14: end for 15: CBL.append({BCS , ni, ACS }) 16: N ∗ .remove(ni) 17: end if 18: N.remove(ni) 19: end while 20: return CBL

We define a CallSite List (CSL) to track change propagation in the dependency graph. We begin by identifying the node with the minimum in-degree. If this node is a Callsite node, we determine the impacted statement nodes from Callsite Analysis based on the API granularity and change scope. Nodes connected by dependency edges are recorded as After Callsite (ACS), while those connected by reverse dependency edges are recorded as Before Callsite (BCS). Consequently, all code segments affected by this Callsite node are aggregated into {BCS,Callsite node,ACS}. We then decrement the in-degree of each of the impacted statement nodes by one. Repeat the above steps until all Callsite nodes are processed. This algorithm maintains the order of change propagation and aggregates affected code segments, enabling the LLM to apply changes sequentially in later prompts.

3.3 LLM-Based API Migration

To complete the migration for the project, according to the code segments in the CBL, we construct a prompt for each callsite block of API changes, utilizing API evolution knowledge from the APIEvoKG to guide the LLM in generating the migrated code. The structure of our prompt template is illustrated in Figture 4. We begin with the task definition for project-level cross-version library migration p1; provide the code to be migrated p2. Next, we list the statements that contain calls to changed API elements p3. Finally, we present the information from the APIEvoKG, including source entity, change type, target entity, and change scope p4.

P1

• Task Instructions: I update my Java project's dependency Library [Library Name] from version [source_version] to [target_version]. I will provide you with the Code Snippet that has API call problems due to version change. Your task is to modify the Code Snippet based on the information given.
• Target Code Snippet: This is the code that need to migrate, containing the Changed API and Dependent code statements… P2
• API Callsite: The statement containing the changed API Callsite… P3
• API Change information description: <change source element, type, change target element> [scope],[Description] P4

Migrate the "Target Code Snippet" to target version according the given API Change information. Only return the Migrated Code.

Figure 4: Prompt Template

4 Experiments

4.1 Datasets

Dependency Library. The cross-version API migration task aims to modify the project in response to update in dependency library. We select library for migration based on their current popularity in Maven, the frequency of version changes, and previous research on libraries migration. For our study, we choose Lucene, an open-source information retrieval library. Following the principles of semantic versioning principles [Preston-Werner, 2013; Lam et al., 2020] where major versions indicate breaking API changes while minor/patch versions are used to maintain backward compatibility or bug fixes, we analyzed Lucene's evolution from version 4.0.0 to version 10.1.0 (Oct 11, 2012 - Dec 20, 2024) - encompassing 7 major versions and 118 total subversions - to extract API and change information and construct a comprehensive version evolution knowledge graph.

Dataset for Migration Projects. Previous API migration tasks primarily concentrated on code block-level migrations, lacking comprehensive data on cross-version project migrations. Utilizing the dataset construction methodology detailed in [Zhong and Meng, 2024], we expanded and developed a dataset of API usage example projects in 7 major versions of Lucene, all released by Apache, ranging from version 4.0 to 10.0. Based on these projects, we built 28 migration pairs, involving different version spans, from a span of 0 version to that of 6 versions.

4.2 Metrics

We employ two primary evaluation metrics, CodeBLEU (CB) and Valid Code Element Usage Rate (VCEU), to evaluate our method for handling changes across multi-version libraries in projects.

• CodeBLEU [Ren et al., 2020] evaluates the quality and accuracy of the generated code by comparing its structure, syntax, and vocabulary with the ground truth in the target version. CodeBLEU = 0.25 · MatchN-gram + 0.25 · MatchWeighted N-gram + 0.25 · MatchSyntactic AST + 0.25 · MatchSemantic data-flow.
• VCEU evaluates the validity of API changes by matching API-related keywords against the ground truth with regular expressions. Score = nk , where n is the number of matched keywords from total keywords k.

4.3 Baselines

We compare our results with baseline methods that utilize LLMs, including Automatic Library Migration (FR), VERSICODE, and CodePlan, using the aforementioned datasets.

• FR[Almeida et al., 2024]: This method introduces a set of prompts designed to guide LLMs in generating migration code. We compare two types of prompts: FRb(Zero-Shot) and FRc(Chain of Thoughts).
• VERSICODE(VC)[Wu et al., 2024]: This approach introduces the version-aware code migration task and provides prompts to validate the model's ability to migrate code between specified versions.
• CodePlan(CP)[Bairi et al., 2024]: This model tackles project-level code editing tasks by providing contextual information within a class to aid in generating code.

4.4 Implementation Setup

We employ LLMs to accomplish API migration tasks. For the selection of LLMs, we choose the most popular LLMs: Claude-3, DeepSeek-V3, GLM-4, and GPT-4o. Our model parameter settings are configured as follows: the Temperature is set to 0.7 to strike a balance between text diversity and coherence during the generation process, while Max Tokens is capped at 512 to ensure the readability of the code fragments. Additionally, to enhance the robustness of our experiments, we allow each LLM to generate results independently 5 times, reporting the average in our paper.

4.5 Main Results

Table 1 presents the comparison between APIMig and baseline methods across four LLMs. Our approach achieves superior performance in cross-multi-version API migration tasks.

Taking GPT-4o as an example, APIMig achieves a 16.52% average improvement over the state-of-the-art method CodePlan in the CodeBLEU metric for all spans. Specifically, for small version spans (span ≤ 2 major versions), the improvement is 13%, while for large spans (span ≥ 3 major versions), it rises to 19.16%, particularly reaching 21.58% for span-3. Compared to FRb, FRc, and VC, APIMig shows average improvements of 24.81%, 29.09%, and 21.14% in 6 spans, respectively. Furthermore, in the VCEU metric, APIMig achieves a 28.49% average improvement for all spans, including a remarkable 36.90% improvement for large spans. Against FRb, FRc, and VC, it outperforms 33.17%, 42.83%, and 33.9% on average in 6 spans respectively.

The results show the superiority of our approach over traditional prompting and chain-of-thought methods in API migration, showing its ability to generate critical code elements. Additionally, experiments on Claude-3, DeepSeek-V3, and GLM-4 further verify APIMig's robustness, demonstrating its adaptability to diverse LLMs.

4.6 Ablation Studies

As shown in Figure 5, we conducted an ablation study on APIMig to investigate the contributions of its key components: (1) removing API evolution information from the knowledge graph (w/o KG), and (2) eliminating code segments in the change chain (w/o Change Chain Impact).

Our results demonstrate that both components are essential for optimal performance. Without the API Evolution Knowledge Graph, LLMs relies only on the training corpus to generate migration code, causing a 33.08% average VCEU metric drop in different spans. The VUEC metric decline confirms that missing API information significantly limits accurate and relevant migration code generation, highlighting the critical role of APIEvoKG in providing version-specific API knowledge.

Without Chain of Changes Exploration, CodeBLEU and VCEU decrease by 22.98% and 5.35%, respectively, demonstrating that third-party API changes propagate through dependency chains rather than occurring in isolation. This performance drop reveals the model's difficulty in accurately identifying modification locations without understanding contextual code dependencies, highlighting the necessity of dependency information for effective migration.

4.7 Case Study

Figure 6 demonstrates our solution during an upgrade of Lucene in the project from version 4.10.4 to 7.3.1. We utilize our APIEvoKG to generate a cross-version API Change List through reasoning. Then, we build a dependency graph for the project code that requires migration and apply the chain exploration algorithm to pinpoint the affected code that needs updates throughout the project. For instance, the API change on line 128 modifies the invoking method's name and the return value type, which in turn affects line 222, where a function declared on line 115 is invoked. Finally, we use a prompt to guide the LLM to generate the result. Compared to baseline methods, our method correctly utilizes the change information and applies the appropriate contextual content to generate migration code.

5 Threats to Validity

This study proposes a project-level code generation method for migrating APIs across versions using an APIEvoKG. While our method shows significant capabilities, it faces limitations, such as the scarcity of relevant datasets for thirdparty libraries and open-source projects[Liu et al., 2023]. Our knowledge graph relies on official documentation and change logs, which may have inconsistencies and missing information, affecting change reasoning accuracy. Additionally, automated entity extraction and relationship identification may introduce errors, especially with complex changes. To mitigate this, we have manually reviewed the extraction results to minimize errors.

6 Conclusion

In this work, we propose a cross-multi-version API migration framework (APIMig), which provides cross-version evolution knowledge of APIs in libraries through the reasoning of the API Evolution Knowledge Graph and locates the impact scope of API changes in the project code using a chain exploration algorithm. Based on a large language model, it facilitates the migration of code within the project. This approach dynamically expands the cross-version API knowledge of the LLMs while precisely identifying the code that needs to be modified in context, thus enabling API migration. Experiments conducted on cross-version projects demonstrate the effectiveness of our proposed method, which achieves competitive results across various cross-version pairs, proving the method's effectiveness and robustness in cross-version library migration projects.

Acknowledgments

This work has been supported by the National Natural Science Foundation of China under grant No.62472447 and 62472132, Hunan Provincial Natural Science Foundation of China under grant No.2024JK2006, the Science and Technology Innovation Program of Hunan Province under grant No.2023RC1023, Key R&D Program Project of Zhejiang Province under grant No.2025C01063 and 2024C01179, the Fundamental Research Funds for the Central Universities of Central South University. This work was carried out in part using computing resources at the High Performance Computing Center of Central South University.