API management platforms answer many operational questions reliably. They show which APIs are available, which routes they can be reached through, which policies apply, and which consumers have been registered. For architecture, governance, and modernization, however, this perspective is often insufficient. The problem is not necessarily a lack of data. Most often, the information created by the context and relations between data is not adequately searchable or mapped through a user interface.

Usage data resides in monitoring systems, technical configurations in API management, contracts in repositories or registries, responsibilities in organizational directories, and business domain mappings in architecture models or within the heads of individual teams. Every system shows a relevant excerpt. Yet, using all these excerpts, many questions can only be answered with numerous clicks and high manual effort. A transparent picture of the API landscape fails to emerge.

For this, an additional knowledge layer is required. It connects APIs with their contracts, versions, services, consumers, teams, business capabilities, interrelationships, definitions, and runtime data. A Knowledge Graph is one way to technically implement such a layer. The core distinction is: API management organizes the operation of APIs. A knowledge layer organizes the knowledge about these APIs.

Legacy Is Not a Quality Judgement

The absence of relationship knowledge becomes particularly visible with legacy APIs. The term is often associated with outdated technology, poor documentation, or an urgent need for replacement. This interpretation does not adequately reflect the reality of many organizations. Numerous APIs have been running in production for years. They are stable, business-critical, and support processes that cannot be rebuilt quickly or switched off without considerable risk. The fact that an API has existed for a long time says little about its technical quality.

In this context, we use legacy to describe established interfaces that have become embedded in an evolving system landscape over time. While the API continues to fulfil its purpose, the surrounding teams, platforms, responsibilities, and business requirements change. The situation becomes difficult when the API retains its business importance while its context becomes increasingly hard to understand. Who owns the API today? Which applications use it? Which services depend on it? Which contracts and versions are authoritative? Which business capability does it support? What would be affected by a change?

The relevant characteristic of a legacy API is therefore not its age. It is the gap between its continuing importance and the available knowledge about its usage, ownership, and dependencies.

An API Inventory Is Not Yet an API Landscape

API management platforms and developer portals create visibility. They show which APIs are registered, which endpoints they expose, which authentication methods they use, and which rate limits apply. They answer many operational questions quickly and reliably. Understanding a landscape requires more than a list of its components. Which consumer application uses a particular operation? Which team owns that application? Which route connects to which service? Which API exists in the gateway but has not been published in the portal? Which subscription exists formally but shows no actual usage?

An inventory describes objects. A landscape emerges from the relationships between them. These relationships are frequently distributed across several systems. The API management platform knows a consumer but not necessarily its business role. The monitoring system knows the number of calls but cannot always associate them with an accountable team or business process. Architecture documentation may describe the intended state, while runtime data reveals which dependencies are being used. The operational view remains necessary. But it does not automatically provide a foundation for architecture and governance decisions across the organization.

The Solution Space Starts with Relationships

These relationships require a shared model. An API is related to its contracts, versions, operations, routes, and services. Consumer applications use those operations. Teams own applications or APIs. Business capabilities describe the organizational abilities supported or implemented by one or more APIs. Policies define access and runtime rules. Monitoring data shows which of the modelled relationships are active.

Example Ontology Model

In simplified form, the relationship chains described above might look like this:

The ontology can be decomposed into individual paths. These paths illustrate which questions can be answered through the relationships.

The first path can be used to investigate which teams and applications might be affected by a change to an API. The graph is traversed from the changed component to the applications consuming it and the teams responsible for them.

The second path connects the technical interface to its business purpose.

Capabilities, however, are rarely stored in an API management system. Adding them to the graph therefore requires additional effort. A machine-readable contract describes the behaviour an API promises to provide. But the relationship between an API and a capability cannot be inferred reliably from gateway metadata, URL paths, or schema names alone.

It requires business knowledge and an explicit, traceable modelling decision. An API may support several capabilities. At the same time, a single capability may be implemented by multiple APIs or by other types of interfaces. The objective of an initial model should not be to create the most comprehensive ontology possible. Modelling should instead begin with concrete questions:

Which changes currently require the most manual investigation? Which governance checks depend on information from several systems? Where do we lack reliable answers about ownership, capabilities, dependencies, or usage?

A minimal model can be derived from these questions. It should only be extended once it has demonstrated measurable value.

Why a Graph Model Fits This Problem

Efficient Relationship Queries

The value does not come from Neo4j or any graph database. What matters is a data model that treats relationships as information. Relational models usually express relationships through keys and links between tables. This is entirely appropriate for many use cases. A graph model, however, makes relationships directly navigable and analysable. Graph databases are designed and optimized to execute complex queries across these relationships efficiently. A query can move from an API to its contract, then to an operation, route, service, consumer application, and accountable team. It can also start with a capability, identify its available API implementations, and examine their actual usage. As the number and variety of relationships grow, a graph model can often be extended with new analysis paths more easily than a schema designed around a fixed set of reports.

From join complexity to direct navigation in the knowledge graph

In a relational model, queries involving many consecutive joins can require considerable processing and memory. Recombining data may produce large intermediate result sets. Query planning can also become expensive because the database must evaluate possible join orders and algorithms across an increasingly complex search space.

Graph models are optimized for traversing relationships. Relationships are stored as explicit elements or direct references between nodes. Traversals can therefore follow these edges without reconstructing every relationship through join operations at query time, an approach commonly described as index-free adjacency.

This advantage becomes particularly relevant for highly connected data and deep traversals. It does not make relational databases unsuitable, but it changes the cost profile of questions that follow long or variable relationship paths.

Visualization also benefits from a graph model. Highly connected services, central dependency points, and unusual connection patterns are often easier to identify in a graph than in a table. The primary value of the graph model, however, remains efficient machine analysis. Visualization is a useful interface to the model, not its architectural justification.

Resolving Heterogeneous Contexts: A graph can also distinguish explicitly between different meanings of the same term. An object called a “service” in an API gateway does not necessarily represent the same thing as a deployment, a repository, or a business service. A shared model can represent these objects separately while preserving the relationships between them. This becomes particularly useful when the graph serves as the knowledge source for a chatbot. Synonyms and ambiguous terms can then be resolved using the context of the user’s question.

API management platforms, monitoring systems, developer portals, registries, and repositories remain the authoritative sources for their respective information. The graph model connects contracts, runtime data, ownership, capabilities, and dependencies so that questions spanning these sources can be answered.

Landscape Knowledge as a Foundation for Governance

This connection is also relevant to API governance. Before an organization defines rules and automates their enforcement, it should understand the API landscape that exists. Kin Lane describes the discovery of the real API portfolio as the first step towards effective API governance. Rules formulated without sufficient knowledge of the existing landscape often produce many violations. They do not yet provide a viable strategy for change. An inventory of the current landscape makes it possible to align rules with observable patterns and to prioritize their introduction realistically.

Information from API management, monitoring, portals, contracts, and organizational sources can be connected through a shared graph model. This makes it possible to understand how APIs are used, who owns them, which capabilities they support, and what might be affected by a change. Governance findings can then be evaluated in context. A heavily used API with numerous dependent applications may require a different migration path from a rarely used interface with the same deviation. Rules remain necessary, but their prioritization can account for usage, risk, ownership, and impact. For REST API governance, Kin Lane places the machine-readable OpenAPI contract at the centre. Style guides, linting rules, reviews, and pipeline checks operate on this contract. The graph model adds context such as versions, runtime data, ownership, business classification, and dependent consumers.

A knowledge graph does not replace API governance. It provides the landscape knowledge without which governance rules can easily be applied to unclear contracts, obsolete versions, or incorrectly assigned APIs.

A Proof of Concept as an Architectural Investigation

We are currently developing a proof of concept to examine this architectural idea. The PoC investigates whether data from API management and monitoring can be connected through a shared graph model in a way that enables additional forms of analysis. Kong serves as the first API management source and represents an API gateway or API management system. Prometheus provides usage data. Neo4j stores the entities and relationships derived from these sources. Grafana presents selected analyses. A chat interface enables natural-language questions against the graph model. A transformation layer sits between the source systems and the graph. It maps platform-specific objects into the shared knowledge model.

Questions the Model Can Explore

The demonstration focuses on questions concerning usage, governance, and dependencies:

Which APIs and endpoints are used most frequently?
Which consumers generate the highest call volume?
Are there registered subscriptions that show no observable usage?
Which services experience unusual usage peaks?

Other questions concern technical governance:

Which endpoints have no authentication plugins?
What proportion of API calls is successful?
Where do configurations deviate from expected rules?

For change impact analysis, the model includes relationships between services, routes, API operations, consumer applications, and teams. This makes it possible to follow the path from a technical change to the consumers that could potentially be affected. The quality of the result depends on whether the necessary relationships are complete and current.

API sprawl is also part of the solution space. Similar names, paths, or schemas may indicate overlaps, but they do not prove business redundancy. Two structurally similar interfaces may serve different user groups, quality requirements, or areas of responsibility. A more reliable assessment must therefore consider which capability an API supports and whether several interfaces are genuinely alternative implementations of the same business ability. Only the combination of structural or semantic similarity, capability classification, and actual usage provides a defensible basis for consolidation decisions.

In his work on measurable reuse, Kin Lane argues that the relevant unit of reuse is not the individual API but the capability. Several APIs may represent different implementations of the same capability. He also distinguishes between reuse potential and actual adoption, using consumer and traffic data as part of the assessment. A knowledge graph can connect capabilities, their different implementations, technical characteristics, and demand data. It can provide evidence for a consolidation decision, but it cannot make that decision by itself. A heavily used but technically imperfect API may be more operationally relevant than a more elegant alternative without active consumers. The chat interface simplifies access to these queries. Its reliability depends directly on the underlying model. It can make existing knowledge accessible, but it cannot compensate for missing relationships or absent business assessments.

The Real Challenge Lies in the Data

A graph database can be installed quickly. Building a reliable knowledge layer is considerably more difficult. One of the most challenging tasks is identifying and matching objects from different sources. Is an API registry entry, a gateway service, and a repository separate object, or are they different representations of the same system? Similar names are rarely sufficient to answer this question. Governance also requires clarity about which contract is canonical, which version is being assessed, and who is accountable for it. Without this information, a rule may be executed correctly from a technical perspective while still being applied to an obsolete or non-authoritative artefact. Kin Lane identifies precisely these unclear sources, versions, and stakeholders as a central problem in mapping an API landscape.

Connecting static configuration to runtime data is similarly demanding. A subscription initially represents permitted or intended usage. Only metrics show whether that relationship is active in practice. Missing ownership, inconsistent terminology, and obsolete information become more visible through the shared model. Correcting them, however, remains the responsibility of the relevant processes and source systems. The shared vocabulary also requires maintenance. Terms such as API, service, consumer, capability, and product must be sufficiently unambiguous. A technical operation must not be equated prematurely with a business capability. Without agreed definitions, the model becomes harder to understand with every extension.

Finally, relationships, their origins, and their status must remain traceable. A one-time import may be sufficient for a demonstration, but not for architecture or governance decisions. Synchronization and data provenance must therefore be part of any production architecture.

From a PoC to a Platform-Independent Knowledge Layer

A later stage could incorporate AsyncAPI descriptions, repositories, CI/CD results, and architecture models. This would enrich technical metadata with contract information, implementation details, governance results, capabilities, and further business classifications. Different API gateways and API management platforms should also be supported. This requires the knowledge layer to have its own platform-independent model and clearly separated adapters for the source systems. Only then can it remain independent of the terminology and structures of an individual vendor. Over time, governance decisions could also become part of the model. A finding could be connected to its review, accountable team, resulting decision, rationale, and the validity period of an exception. Kin Lane describes this type of provenance as a foundation for accountability. The relevant information is not only that a finding exists, but also who assessed it and which decision followed.

The knowledge layer could therefore make not only the current state accessible, but also part of the organization’s decision history. Expansion should remain incremental. Rather than modelling the entire integration landscape immediately, it is more useful to begin with a clearly bounded scenario: a change impact analysis, the identification of unused subscriptions, or the verification of security-relevant policies. Such a scenario limits the scope of the model and makes its value testable. Based on the result, the organization can decide which additional data sources, adapters, and relationships are required.

API Management Needs a Complementary Knowledge Layer

As an API landscape becomes larger and more heterogeneous, the operational view provided by individual platforms is no longer sufficient. Architecture, governance, and modernization require a shared model of contracts, capabilities, actual usage, ownership, and dependencies. A graph-based knowledge layer can connect this information and make it queryable. Its value lies neither in a particular database nor in the visualization. It lies in a traceable model of the relationships that shape the API landscape. The proof of concept investigates one concrete technical implementation. The underlying architectural thesis reaches further: API management organizes the operation of APIs. A knowledge layer organizes the knowledge required to understand and evolve APIs as part of their technical, organizational, and business landscape.