API Graphs

• API Graphs are formal, graph-structured representations that model API relationships, dependencies, and semantics to support composition, testing, security, and orchestration in software systems.
• They enable practical applications such as API composition, usage recommendation, automated repair, dynamic testing, and secure orchestration across heterogeneous systems.
• Recent research shows that API graphs boost tool retrieval accuracy, enhance misuse detection through parameter-level modeling, and improve dynamic integration in federated API ecosystems.

API graphs are formal graph-structured representations that encode the relationships, dependencies, and semantics of Application Programming Interfaces (APIs), their operations, parameters, or usages. They underpin a growing set of methodologies across API composition, usage recommendation, automated repair, interaction planning for tool agents, dynamic testing, security, and the orchestration of complex tasks within and across software systems. Recent research delineates diverse incarnations and applications of API graphs, including but not limited to knowledge graph construction via APIs, parameter-level dependency graphs for tool planning, usage graphs for misuse detection, heterogeneous multi-view graphs for usage recommendation, and federated graphs constructed on demand from semantically annotated APIs.

1. Structural Typologies and Construction of API Graphs

API graphs exhibit several structural paradigms depending on their intended purpose and the level of granularity required:

• Entity–Relation Knowledge Graphs: Approaches such as the RESTful service for knowledge graph construction accept semantic descriptors (via JSON Schema and Meta Schema) for nodes and edges, representing concepts, roles, and inheritance relationships (e.g., $\mathcal{O} = (C, R, \text{isa})$). The knowledge graph itself is often modeled as $G = (V, E, L, \alpha)$, where $V$ is the set of vertices, $E$ the edges, $L$ the labels, and $\alpha$ a mapping of properties (Agocs et al., 2018).
• Parameter-Level API Graphs: In the “In-N-Out” dataset, API graphs are constructed by representing both entire APIs and individual parameters as nodes, with directed edges from output parameters of one API to input parameters of another where dataflow is possible and semantically coherent. This structure is derived via multi-stage (rule-, semantic-, context-based) filtering of possible pairings, with connection strengths (“strong”, “weak”, “non”) annotated by experts (Lee et al., 1 Sep 2025).
• API Usage Graphs (AUGs): These graphs model program API usages at the method or snippet level as labeled, directed (multi)graphs. Nodes denote method calls, data objects, or control-flow constructs, while edges encode dataflow (for instance, parameters and returns) and control flow (such as execution sequence) (Nielebock et al., 2021, Nielebock et al., 12 Feb 2024, Nielebock et al., 2022).
• Multi-View Heterogeneous Graphs: Some recommendation systems, such as MERIS, employ three-layered graphs—call interaction (method–API bipartite), API co-occurrence (global API–API), and hierarchical structure (context such as project, class, or package)—with distinct edge semantics in each (Chen et al., 2022).
• Federated Knowledge Graphs of APIs: In systems like BioThings Explorer, a virtual graph model is induced at query-time, with nodes as biological entity types and edges corresponding to semantically annotated web service calls. The meta-graph (meta-KG) is encoded via the registry annotations (e.g., semantic types, predicates, ID namespaces) (Callaghan et al., 2023).

Graph construction in each case typically involves transforming some combination of code, API documentation, data schemas, or web service annotations into a graph formalism, often with an explicit type system or set of construction rules to encode permissible interconnections.

2. Dependency Modeling and Operational Composition

Explicit modeling of data and control dependencies is central to the utility of API graphs:

• Parameter Dataflow and Tool Orchestration: In parameter-level API graphs, directed edges may exist only if output and input parameters are type- and context-compatible and reflect natural tool orchestration; for instance, a “document_id” output from an upload API may directly fulfill an input requirement for a share or edit API (Lee et al., 1 Sep 2025).
• Compositional Multi-API Queries: Explicit graphs enable tool agents (LLM-based or otherwise) to plan multi-step API invocations, selecting and sequencing API calls so that outputs fulfill the dependencies of subsequent inputs, even across heterogeneous or cross-domain APIs. Performance on such planning tasks is improved nearly twofold compared to approaches that rely on unstructured documentation alone (Lee et al., 1 Sep 2025).
• REST and GraphQL Query Graphs: In GraphQL, queries themselves are trees (subgraphs of the backend schema graph), while access control models, federated planning (where queries are broken into subgraphs for individual services), and batched executions all rely on explicit graph representations and dependency mapping (Amareen et al., 15 Aug 2024).
• Dynamic and Federated Graph Expansion: Systems like BioThings Explorer construct dynamic subgraphs on-the-fly by chaining semantically annotated API calls together based on user-supplied query graphs, translating data between identifier spaces, and integrating disparate API outputs into a unified graph structure (Callaghan et al., 2023).

Such explicit encoding of dependencies provides the basis for automation, compositional logic, and scalability in API orchestration.

3. Analysis, Recommendation, and Automated Repair via API Usage Graphs

API usage graphs (AUGs) are a key abstraction for program analysis, error detection, and repair:

• API Misuse Detection: AUGs encode the sequence and flow of API calls in a program and can be compared using a variety of graph distance algorithms—graph edit distance, maximum common subgraph, node-node similarity, and feature vectors (e.g., Exas vectors)—to flag deviations from correct usage or template graphs (Nielebock et al., 2021). Rule-based and change-rule methods use pairwise distances to determine if a new usage instance is closer to a known misuse or its fix, formalized as $$\mathrm{dist}(aug_{mr}, aug_x) < \mathrm{dist}(aug_{rc}, aug_x)$$ (Nielebock et al., 2022).
• Automated Program Repair (APR): In techniques like ASAP-Repair, detected misuses are repaired by transforming the AUG (using node/edge insertions, deletions, substitutions via a minimum-cost matching such as the Kuhn–Munkres algorithm), so its structure matches that of a correct template or the “fixed” part of a historical change rule (Nielebock et al., 12 Feb 2024). Three primary transformations are identified: updating nodes/edges, adding missing nodes/edges, and deleting erroneous components.
• Limitations and Challenges: AUG-based methods face challenges of subgraph isomorphism complexity, the need for precise feature/weight selection in distance computation, unreliable cross-project generalization, and the translation of repaired graphs back to actual code, especially beyond acyclic graphs or for multi-API repairs (Nielebock et al., 2021, Nielebock et al., 12 Feb 2024).

The evidence indicates high-precision, low-recall behavior for such detectors: when rules apply, they are accurate (77–96% mean relative precision), but recall is often low because rules are highly specific (Nielebock et al., 2022).

4. API Graphs for Tool Agents, Multi-API Planning, and Intelligent Interfaces

The parameter-level API graph paradigm directly supports emerging tool agent architectures, particularly for grounded LLM agents:

• Explicit API Graphs for Tool Retrieval and Multi-Tool Planning: The In-N-Out dataset demonstrates that making parameter dependencies explicit yields major improvements (up to 41% increase in top-1 accuracy and large reductions in average rank error) in both tool retrieval (identifying which API to call next) and multi-tool query generation compared to documentation-only approaches (Lee et al., 1 Sep 2025).
• Graph Construction Methodology: Construction of high-utility API graphs combines rule-based type filtering, semantic similarity (embedding-based), context-aware LLM scoring, and human expert annotation of edge strength. The distinguishing feature is the edge granularity: relationships are not simply API-to-API, but parameter-to-parameter, admitting fine-grained dataflow planning.
• Model Generalization and Fine-Tuning: Fine-tuned LLMs (e.g., Llama, Qwen2.5-32B) on In-N-Out close 90% of performance gap with respect to gold (human-annotated) graphs, and generalize across APIs/domains (Lee et al., 1 Sep 2025).
• Federated and Modular Knowledge Graph Use with LLMs: In specialized domains (e.g., meteorology in KG2data), knowledge graphs serve as persistent, updatable memory modules that inform LLM-based tool agents. This allows for precise API call planning, reduction in hallucination rates (to 0% in KG2data), and high call accuracy (88.57%), as well as low cost adaptation to domain changes without continual model retraining (Yang et al., 14 Jul 2025).

Overall, these advances facilitate realistic and scalable multi-agent or LLM-based systems that can reason compositionally about large tool/APIs sets without incurring untenable search or planning bottlenecks.

5. Security, Testing, and Resource Management in Graph-Based API Architectures

API graphs play a foundational role in advancing robust security and scalable testing methodologies:

• Taint Analysis and Information Flow Security: Modeling Graph API calls as graph transformation rules (triples $(L \leftarrow K \rightarrow R)$) supports systematic taint analysis for detecting broken access control. Critical Pair Analysis (CPA) computes dependency reasons between source and sink rules to flag direct or indirect propagation of sensitive (tainted) data through API call sequences, supporting static and dynamic validation as applied to real GraphQL APIs (e.g., GitHub) (Lambers et al., 15 Jan 2025).
• Semantic Graphs in REST API Testing: AutoRestTest employs a semantic property dependency graph (SPDG) that encodes semantic producer–consumer relations among API operations, derived from both static API specification and dynamic test feedback. Integration of SPDG within a multi-agent, RL-driven testing framework yields substantial gains—up to 15.38% more operation coverage and up to 9.2× more faults detected compared to leading baselines—demonstrating that graph-guided exploration is a powerful boost to test efficiency (Kim et al., 11 Nov 2024).
• Microservice System Modeling and Benchmarking: In microservice architectures, a Service Dependency Graph Generator builds call graphs representing production traces, accurately encoding not only call topology but dynamic interface usage, repeated invocations, sibling set influences, and communication modalities (HTTP, RPC, etc). Fine-grained modeling yields resource scalability improvements up to 44.8% while ensuring service-level QoS (Du et al., 26 Dec 2024).

These findings collectively underscore the instrumental value of graph-based abstractions for enforcing security policies, guiding effective testing, and modeling real-world API-driven applications.

6. Practical Applications and Ecosystem Impact

API graphs increasingly underpin a wide range of applications across software engineering:

• Knowledge Graph Construction and Semantic Data Integration: The RESTful JSON Schema approach provides formalized, scalable data ingestion and semantic validation for constructing knowledge graphs in domains requiring rich, evolving ontologies (Agocs et al., 2018).
• Semantic Web, SPARQL, and Simplified RESTful APIs: Representing RDF graphs as object-oriented, navigable JSON structures (with CRUD operations mapped over SPARQL) reduces the technical barrier for web developers, promoting the adoption of semantic technologies (Schröder et al., 2018).
• GraphQL Ecosystem and Security: Graph APIs (see, e.g., GraphQL) provide granular, compositional query interfaces, but pose unique security and operational challenges—particularly in access control, query complexity, and federated execution—requiring explicit graph models both for schema definition and runtime enforcement (Amareen et al., 15 Aug 2024, Lambers et al., 15 Jan 2025).
• Malware Detection: API knowledge graphs and contrastive learning help model evolution-invariant “semantics” of malware, boosting detector performance and sustainability across evolving threats (Wei et al., 3 Aug 2024).
• Biomedical Knowledge Integration: Federated, semantically annotated biomedical APIs enable real-time knowledge graph merging for drug repurposing and clinical decision support without centralized repositories (Callaghan et al., 2023).

7. Limitations, Open Problems, and Outlook

Despite the documented advances, several limitations remain:

• Expressiveness and Standardization: JSON Schema/Meta Schema–based models for API graphs, while extensible, do not match the expressiveness of ontology-based languages (e.g., OWL), and struggle to represent advanced forms of inheritance or reasoning (Agocs et al., 2018).
• Scalability and Performance: While bulk operations are efficient, single API graph operations can incur high validation cost as data grows, and graph matching remains a computational bottleneck (Agocs et al., 2018, Nielebock et al., 2021).
• Metric Reliability and Feature Engineering: Existing generic graph distance algorithms are of limited precision/recall for real-world misuse detection. Continued research into weighting, feature selection, and context restriction is necessary (Nielebock et al., 2021).
• Evolution and Maintenance: Support for evolving schemas and cross-version interoperability (especially for API graphs derived from live documentation and real-world production traces) continues to demand methodological and engineering attention (Du et al., 26 Dec 2024, Yang et al., 14 Jul 2025, Lee et al., 1 Sep 2025).

API graphs thus constitute a unifying abstraction spanning data modeling, operational composition, security and testing, and tool agent planning. Their development reflects ongoing integration of symbolic, statistical, and graph-theoretic techniques, providing both immediate practical utility and a platform for continued research into more reliable, efficient, and intelligent API-driven systems.