Dynamic API Graph for Automated API Synthesis

• Dynamic API Graph is a knowledge graph-based formalism designed to represent and evolve web-accessible APIs through attributed directed graph structures.
• It encodes API declarations, parameters, and natural language expressions using typed edges and semantic similarity metrics for context-aware mapping.
• The approach enables automated synthesis of API calls from free-form user utterances, yielding higher precision, recall, and invocation accuracy versus static methods.

A Dynamic API Graph is a knowledge graph-based formalism for representing and evolving the structure, semantics, and invocation logic of web-accessible application programming interfaces (APIs). Designed to facilitate automated synthesis of API calls from natural language expressions, the Dynamic API Graph approach encodes APIs, their declarations, parameters, parameter values, expressions, and semantic similarity information using an attributed directed graph structure. It supports dynamic enrichment via machine learning, user interaction, and word-embedding models. This enables robust mapping from free-form user utterances to concrete, correct API invocations at runtime, outperforming static rules and template-driven methods across precision, recall, invocation accuracy, and coverage metrics (Zamanirad et al., 2017).

1. Formal Definition and Schema

The Dynamic API Graph is formalized as a labeled, attributed directed graph: $G = (V,\,E,\,\mathcal{A})$

• $V$: set of nodes (entities)
• $E \subseteq V \times V$: set of directed edges (relations)
• $\mathcal{A}: V \cup E \to \{\text{attributes}\}$: maps nodes and edges to attribute sets

Nodes $V$ are partitioned by entity type: $$V = V_{\mathrm{API}} \cup V_{\mathrm{Decl}} \cup V_{\mathrm{Param}} \cup V_{\mathrm{Value}} \cup V_{\mathrm{Expr}} \cup V_{\mathrm{WE}}$$

• $V_{\mathrm{API}}$: API entries (e.g., “Yelp API”)
• $V_{\mathrm{Decl}}$: Declarations (e.g., method+endpoint)
• $V_{\mathrm{Param}}$: Parameters (e.g., 'term', 'location')
• $V_{\mathrm{Value}}$: Concrete parameter values (e.g., “Italian”)
• $V_{\mathrm{Expr}}$: Natural language expressions (e.g., “Find Italian restaurants in Sydney”)
• $V_{\mathrm{WE}}$: Word-embedding neighbors for semantic enrichment

Edges $E$ are typed: $E = \bigcup_{\tau \in \mathcal{T}} E_\tau$ where $$\mathcal{T} = \{\text{hasDecl}, \text{hasParam}, \text{hasValue}, \text{exprOf}, \text{similarTo}\}$$.

Attributes on nodes and edges encode metadata such as API descriptions, HTTP methods, parameter types, value literals, expression texts, and cosine similarity weights for semantic proximity (for similarTo edges).

2. Construction and Evolution

Dynamic construction of the API knowledge graph occurs as APIs are introduced via developer registration or crowdsourcing. The process incrementally adds API nodes, declarations, parameters, and sample utterance expressions, linking them through typed edges (“hasDecl”, “hasParam”, “exprOf”), as illustrated by:

• Each API $A$: Insert node $a$ with metadata
  • For every declaration $d$: Insert node $d$, edge $(a,d)$
  • For every parameter $p$: Node $p$, edge $(d,p)$
  • For each value $v$: Node $v$, edge $(p,v)$
  • For each sample expression $x$: Node $x$, edge $(x,d)$

Enrichment leverages word-embedding models (e.g., Word2Vec):

• For each $(p,v)$: Retrieve top-K neighbors $\{u_i\}$ with cosine similarity above $\theta$
  • Insert word-embedding nodes $u_i$ as needed, add “similarTo” edges with similarity weights

Online updates support new parameter values introduced at runtime. If a user provides a new value $v'$ for parameter $p$ with a confidence score $\sigma$ above a threshold $\tau$, the value is inserted into the graph as a “hasValue” edge annotated by $\sigma$.

3. Storage and Retrieval of API Metadata

All API metadata is encoded via node and edge attributes, supporting input/output schemas, type constraints, usage patterns, and authentication requirements.

• Declaration nodes ($d$) expose $\mathcal{A}(d).\mathit{inputSchema}$, $\mathcal{A}(d).\mathit{outputSchema}$
• Parameter nodes ($p$) store fields for requiredness, type, and pattern constraints
• API nodes ($a$) contain authentication attributes (e.g., OAuth2, APIKey)

Graph traversal enables metadata retrieval. For instance, the set of required input parameters for a declaration $d$ is: $$\mathrm{Inputs}(d) = \{\,p \mid (d,p)\in \mathrm{hasParam} \land \mathcal{A}(p).{\mathrm{required}} = \mathrm{true} \}$$

4. Mapping Natural Language Utterances to API Calls

Given an utterance $S = w_1 \dots w_n$, the system:

• Computes its vector embedding $\mathbf{S} = \sum_{i=1}^{n} \mathbf{w}_i$ via word embeddings
• For each stored sample expression $T^k$, computes $\mathbf{T}^k$ and cosine similarity
• Selects the declaration $dec^*$ associated with the best-matching expression

Parameter binding:

• Extracts entities $e$ from $S$
• For each parameter $p_i$, finds value $$v^*_i = \arg\max_{v \in \mathrm{Values}(p_i)} \cos(\mathbf{e}, \mathbf{v})$$
• Populates parameters with top-matched values, forming a parameter-value matrix

Slot coverage is computed to ensure all required parameters are properly bound: $$\mathrm{coverage}(dec_k) = \frac{1}{N} \sum_{i=1}^N \mathbf{1}\{p_i \mapsto v_i\}$$ Only if $\mathrm{coverage}=1$, the API call is synthesized and invoked.

Worked Example: For a fragment with Yelp’s GET /search endpoint, given user input “Show me Chinese food places in Sydney”, the system extracts entities (“Chinese”, “Sydney”), maps to parameter values via cosine similarity, and forms the API call:

GET https://api.yelp.com/v3/businesses/search?term=Chinese&location=Sydney

Results are retrieved and returned to the user.

5. Comparative Performance Metrics

Empirical comparison of dynamic KG-based synthesis to static intent and template-driven mapping approaches on a 200-utterance evaluation shows:

Method	Precision	Recall	Invocation Accuracy	F1-score
Static intents	0.78	0.72	0.65	0.75
Template-based	0.82	0.77	0.71	0.79
Dynamic KG + WE (ours)	0.91	0.88	0.85	0.89

The dynamic KG approach also achieves higher slot-filling coverage (0.93 vs 0.80 for templates). Invocation accuracy (first synthesized call correctly succeeds) is 85% for the dynamic method, which is an approximately 20% absolute improvement over static baselines (Zamanirad et al., 2017).

6. Significance and Broader Context

Modeling APIs dynamically as knowledge graphs supports scalable, extensible, and runtime-adaptable API mediation for natural language interfaces. Rich semantic typing, graph-based retrieval, and word-embedding enrichment allow flexible, context-aware interpretation absent from template or statically-coded intent systems. This approach enables continuous evolution—by integrating new APIs, discovering new parameter values, and learning semantic associations from real user interaction and modern natural language processing methods.

A plausible implication is that such techniques generalize to other application modalities where mappings from unstructured signals (e.g., utterances, descriptions, or queries) to structured action spaces (such as robotic controllers, data transformation pipelines, or dynamic API orchestration in biomedical informatics) are required.

7. Related Approaches and Domain Extensions

The methodology of representing dynamically-evolving structured resources as attributed, semantically-enriched knowledge graphs and exposing them via API-centric interfaces has also been applied in the biomedical domain, exemplified by Bio-KGvec2go (Ahmad et al., 9 Sep 2025). While the core focus of Bio-KGvec2go is on updating graph embeddings for biomedical ontologies and serving these embeddings via a REST API, both systems employ dynamic data ingestion, graph-based modeling, vector space enrichment, and API-oriented access as foundational principles.

Both lines of work demonstrate that dynamic API graphs and knowledge graph APIs enable automated, accurate, and up-to-date mapping between complex structured resources and downstream user/system intents, with significant ramifications for both conversational software and information integration pipelines.