API Discovery and Documentation at the Gateway: Inventory, Ownership, and Drift

An API gateway is a valuable source of discovery evidence because it knows which hosts, paths, methods, policies, and upstreams it is configured to handle. It is not a complete API inventory and cannot generate trustworthy documentation from traffic or routes alone.

A dependable program reconciles four views: the reviewed API contract, the effective gateway state, observed exposure and traffic, and an ownership catalog. Documentation is then published from approved contracts and guides, while differences become owned drift work rather than silent source changes.

Key Takeaways

Treat gateway configuration and traffic as observed evidence, not the sole source of truth.
Give every API an owner, audience, environment, version, data class, lifecycle state, and retirement plan.
Publish reference documentation from a reviewed OpenAPI description plus human-authored guidance.
Reconcile missing, unexpected, duplicated, stale, and unreachable APIs across sources.
Keep public, partner, internal, and administrative catalogs separate by policy.
Verify retirement at the gateway, DNS, upstream, portal, client, and data layers.

Define What “Discovered” Means

Different sources answer different questions:

Source	What it can show	What it cannot prove alone
OpenAPI repository	Intended operations, schemas, security contract, version	That the contract is deployed or accurate
Gateway configuration	Effective route, plugin, upstream, and exposure settings	Undocumented internal calls or application behavior
Traffic observation	Hosts, paths, methods, status, volume, and active clients	Legitimate ownership, complete schemas, or safe authorization
Service catalog	Owner, system, environment, data class, lifecycle	That every endpoint is reachable only as recorded
Developer portal	What approved consumers can find and read	Hidden, shadow, retired, or direct-backend exposure
DNS, load balancer, and cloud inventory	Externally or internally addressable surfaces	API semantics and policy correctness

Discovery should create a candidate or discrepancy, not automatically publish an API. Observed traffic can include scanners, typo paths, private data, and deprecated clients.

Reconcile Four Views

flowchart LR
    C[Reviewed OpenAPI and guides] --> R[Reconciliation service]
    G[Effective gateway inventory] --> R
    T[Observed hosts paths methods and clients] --> R
    O[Ownership and lifecycle catalog] --> R
    R --> D[Drift queue with owner and severity]
    R --> P[Approved documentation release]
    P --> X[Public partner or internal portal]
    D -->|reviewed correction| C
    D -->|reviewed gateway change| G

The reconciliation service compares evidence. It does not copy runtime state into source or publish observed traffic automatically. Each correction follows the owner of the defective artifact.

Build the Inventory Record

Use stable identifiers rather than only display names. A useful record includes:

API and operation ID;
owning team and on-call destination;
business purpose and supported consumers;
public, partner, internal, or administrative audience;
environment, region, hostname, base path, and protocol;
contract version and gateway configuration revision;
authentication, coarse authorization, and sensitive-data classification;
upstream service and bypass controls;
lifecycle state: proposed, active, deprecated, retired, or exception;
deprecation date, replacement, last observed use, and retirement owner;
documentation URL and last verification result.

OWASP API Security Top 10 2023 identifies Improper Inventory Management as a risk involving unclear hosts, environments, versions, documentation, and retirement. Inventory is therefore an operational security control, not just a portal index.

Use OpenAPI as the Reference Contract

OpenAPI 3.1.2 defines a language-agnostic description that lets humans and computers understand an HTTP API surface. An OpenAPI Description can feed reference documentation, validation, tests, and client tooling.

It still needs review. Verify paths, methods, parameters, schemas, responses, servers, security requirements, examples, and external references against the deployed behavior. OpenAPI also warns that external resources may be untrusted, reference cycles can exhaust tools, and Markdown or HTML fields require sanitization.

The Operation Object's deprecated Boolean defaults to false. With true, consumers are told to avoid the operation; with false or omission, the document does not promise indefinite support. Neither branch disables the route at the gateway. Retirement needs a separate traffic and lifecycle action.

Reference documentation is only one layer. Add task-oriented quick starts, authentication setup, error handling, limits, examples, changelogs, migration guidance, support, and status information. The companion guide Using OpenAPI for API Documentation covers the contract-authoring workflow.

Collect Gateway Evidence Safely

For Apache APISIX 3.19.0, the Admin API exposes Route, Service, Upstream, Consumer, certificate, and other configuration resources. Read access to that API is still privileged: configuration can reveal internal hosts, plugin settings, identity structure, and secret references.

Use a restricted operator network and managed credential. Export only the fields needed for inventory, redact secrets, tag the source cluster and revision, and preserve collection time. A successful read says what the selected control plane returned; it does not prove every data plane applied the same revision or that direct upstream exposure is absent.

Normalize route evidence into stable fields such as:

{
  "gateway_cluster": "prod-eu-a",
  "route_id": "orders-v2-get",
  "hosts": ["api.example.com"],
  "methods": ["GET"],
  "paths": ["/v2/orders/*"],
  "service_id": "orders-v2",
  "observed_config_revision": "sha256:example",
  "collected_at": "2026-09-22T00:00:00Z"
}

This is an inventory shape, not an APISIX Admin API response schema. The digest is a placeholder and must come from the operator's actual release evidence.

Classify Drift Before Fixing It

Difference	Likely owner	Safe next action
Contract operation missing from gateway	Delivery or rollout owner	Confirm environment and release intent before creating a route
Gateway route missing from contract	API and platform owners	Determine whether it is internal, emergency, stale, or shadow
Traffic on a deprecated version	Product and client owners	Identify allowed clients and execute migration plan
Portal page points to old contract	Documentation owner	Rebuild from the approved version and verify links/examples
DNS or load balancer bypasses gateway	Network and service owners	Close or explicitly govern the alternate path
Owner missing or unreachable	Platform governance	Escalate, restrict exposure if risk requires, and assign stewardship

Do not automatically delete an unexpected route. It may be an authorized incident workaround. Record actor, purpose, expiry, and follow-up, then reconcile through review.

Publish for the Intended Audience

Separate catalog visibility from runtime authorization. Hiding a portal page does not secure a route, and publishing documentation does not grant access.

In API7 Enterprise 3.10.x, API Products can package gateway Services for the Developer Portal and generate documentation from attached OpenAPI specifications. The documentation distinguishes gateway products from external products; external products are not proxied by API7 Gateway and do not support the same subscription or credential path. Treat this as a product-specific publication option, not an Apache APISIX open-source capability.

Before publication, verify:

the product contains only intended Services, hosts, and versions;
visibility matches public or authenticated audience policy;
authentication instructions match the deployed gateway;
examples use non-production placeholders and succeed in the intended sandbox;
limits, error responses, and deprecation notices are current;
internal names, secret references, and sensitive schemas are absent;
the portal release is tied to an approved contract revision.

Retire an API as a Multi-System Change

Deprecation communicates intent; retirement removes supported use. A controlled retirement should:

identify clients and owners without treating a correlation field as trusted identity;
publish replacement and deadline;
prevent new subscriptions or credentials where applicable;
monitor allowed legacy use and contact owners;
remove or deny gateway routes at the approved time;
close direct DNS, load-balancer, and upstream exposure;
remove portal pages or mark archived evidence;
verify that old traffic fails as designed and retained data follows policy.

Keep audit evidence for the decision and final checks. A route returning no recent traffic is not proof that no client depends on it; observation windows, seasonal use, and missing telemetry matter.

Discovery and Documentation Checklist

Does every active API have an accountable owner and support path?
Are contract, gateway, traffic, and catalog revisions recorded separately?
Can the inventory distinguish public, partner, internal, and administrative exposure?
Are external OpenAPI references pinned, bounded, and sanitized?
Are observed paths treated as candidates rather than automatically documented APIs?
Is privileged gateway configuration redacted and access controlled?
Does each drift item identify the defective artifact and its owner?
Do portal visibility and gateway authorization remain separate controls?
Does deprecation include client evidence, replacement, deadline, and retirement action?
Has bypass exposure been checked after a route is removed?