Modern API Management Practices

API management practices have moved noticeably in three years. What was emerging in 2020 — declarative gateway configuration, contract testing in pipelines, AsyncAPI for event-driven contracts, GitOps for API resources, federated developer portals — has crystallised into baseline expectations for new estates in 2023. The leading edge has correspondingly moved: API gateways are now table stakes; the differentiation is in how the broader API estate is governed, tested, and consumed.

This piece is a synthesis of what has moved from emerging to baseline in modern API management, what still distinguishes leading practitioners from average ones, and where the next round of capability is forming.

What has become baseline

The practices that were leading-edge in 2020 and are now expected:

Contract-first development. APIs are designed in OpenAPI (or AsyncAPI for event-driven) before implementation. The spec is the source of truth; implementation is generated against it; documentation, client SDKs, and tests are derived from it. Estates that still write implementation first and document later are behind the current baseline.

Declarative gateway configuration. Gateway resources — routes, policies, plans, applications — are managed as code, version-controlled, deployed through CI/CD. Console-based configuration is no longer the primary management surface for most modern gateways.

Contract testing in CI/CD. Every API change runs against a contract test suite that verifies the implementation matches the published spec. Breaking changes are caught at pull-request time, not in consumer integration testing.

Developer portal as a real product surface. The portal is genuinely usable — API catalogue, interactive documentation, key management, usage analytics, support paths. Portals that are just published OpenAPI docs are below baseline.

Per-API observability with consumer dimensions. Per-API metrics with consumer breakdowns, per-API SLOs, consumer-specific dashboards. Lumping all API traffic into one dashboard is below baseline.

Lifecycle policy with deprecation discipline. A published versioning policy, breaking-change policy, deprecation timeline. Deprecated APIs are retired on schedule, not allowed to drift indefinitely.

Estates that have all of these in place sit at current baseline. Estates that have most of them but a few gaps are still operationally credible. Estates that have several of them missing are noticeably behind the current standard.

What still distinguishes the leading edge

The practices that are still genuinely differentiated:

Async-first API design where the workload fits. OpenAPI handled REST and RPC patterns well; AsyncAPI extended the same discipline to event-driven and streaming patterns. Estates that have AsyncAPI specs for their event-driven surfaces, with the same contract discipline as their REST APIs, are ahead of where most enterprise estates are in 2023.

Federated API catalogue across multiple producers. Large estates have multiple gateways, multiple teams producing APIs, often multiple clouds. A federated catalogue that presents a unified API estate to consumers — across all producers — is harder than running a single gateway. Backstage, Postman API Network, and a few commercial offerings have made this more tractable; few estates have implemented it well.

GitOps for the full API estate. Gateway configuration as code is baseline; the next step is the full API lifecycle as code — contracts, implementations, policies, deployments, deprecations all flowing through Git. The tooling has matured but the operational discipline isn't yet baseline.

Provider-perspective testing. Most contract testing is consumer-side (consumer-driven contract testing, mocking from the spec). Provider-perspective testing — verifying that the provider actually implements the contract correctly, including edge cases the consumer hasn't tested — is more rigorous and less common.

API economics. Treating internal APIs as economic units with cost-to-produce, value-to-consumers, and chargeback. Most enterprises run internal APIs as zero-cost goods; the API teams have no signal about which APIs are actually valuable.

AI-assisted API design. Using LLM-based tools to generate OpenAPI from natural-language requirements, to lint APIs against design guidelines, to identify breaking changes during pull-request review. This is genuinely new in 2023 — early adopters are finding real productivity gains; the tooling will mature considerably over the next year.

What is forming as the next round

The capabilities visible at the leading edge in 2023 that haven't yet matured:

API mesh for service-to-service. Service mesh has handled the within-mesh side of API traffic; API gateway has handled the outside-mesh side. The boundary between them is becoming explicit and tooled. Solo.io's Gloo, Tetrate, Kong Mesh, and similar are positioning here. The category will likely consolidate in the next year or two.

Policy-as-code at the API layer. Open Policy Agent (OPA), AWS Cedar, and similar policy engines are being applied to API authorisation, rate limiting, and routing decisions. The capability is real; the operating model around it isn't yet baseline.

Real-time API analytics for product decisions. Not just operational metrics — analytics that tell product managers which features are adopted, which APIs are growing, which consumers are at risk of churning. The data has always been available; turning it into product-decision input is genuinely new for most estates.

Standardised API security testing. OWASP API Security Top 10 is published; testing tools are improving; CI/CD integration is maturing. Estates that have systematic API security testing in their pipelines are still ahead of average; the practice is likely to become baseline in the next year or two.

Multi-tenant API design discipline. As more APIs serve multiple tenants (partners, business units, regions), the design discipline for tenant isolation, tenant-aware authorisation, and tenant-specific behaviour is becoming a recognised competency. Few enterprises have formalised it yet.

Where many estates are stuck

The recurring gaps we see in API management audits:

Documentation that drifts from implementation. The OpenAPI spec is published but doesn't match what the API actually does. Edge cases, error responses, optional fields — the spec is approximate, not authoritative.

Deprecation policy that exists on paper but isn't followed. APIs declared deprecated five years ago are still in production, with no migration path and no removal date.

Per-API metrics without consumer dimensions. Operations engineers know that "the API is having issues" but can't see which consumers are affected.

Manual gateway changes. Production gateway changes through the vendor console rather than through the deployment pipeline. The changes work; the audit trail is poor; rollback requires manual reversal.

No contract testing. Implementation changes break consumers because the contract is informal. Integration testing is the only verification, and it happens at consumer integration time, not at implementation change time.

These are not advanced gaps — they're baseline practices that haven't been adopted. The leverage for most estates is closing these before reaching for the leading edge.

The relationship to AI-assisted development

A note on 2023's most-discussed development: GitHub Copilot, ChatGPT, Claude, and similar AI coding assistants have changed the API development experience materially. Engineers can generate OpenAPI specs from natural-language descriptions, generate client code from specs, generate test cases against APIs, generate documentation from code.

For API management specifically, the early signals:

• API design productivity is higher; engineers can iterate on contract design faster
• Documentation quality has improved because writing documentation is cheaper
• Test coverage has improved because writing test cases is cheaper
• The boilerplate work around API management is lower-cost than before

What hasn't materially changed:

• Architectural decisions about layering, versioning, deprecation
• Governance discipline
• Operational practices
• Consumer experience design

The leverage is in routine work that took time but didn't require deep expertise. The architecture and governance work still requires the experienced engineers it always required.

What we recommend

For an enterprise API estate evaluating its practice maturity:

1. Audit against the baseline list. Where are the gaps?
2. Close the baseline gaps first. Contract-first development, declarative gateway, contract testing, real developer portal, observability with consumer dimensions, deprecation discipline.
3. Then consider the leading-edge items. Federated catalogue, async-first design, GitOps for the full estate.
4. Bring AI-assisted tooling into the development workflow. The productivity gains are real and the cost is low.

For an estate already at baseline:

1. Identify one leading-edge capability that aligns with your workload. Implement it well.
2. Measure the impact honestly. Did it move the needle?
3. Iterate.

API management as a discipline has matured significantly. The baseline is higher than it was three years ago; the leading edge has moved correspondingly. The estates that compound value over years are the ones that hold to the current baseline and selectively adopt leading-edge capabilities that fit their workload. The estates that adopt the leading-edge labels without the underlying disciplines accumulate complexity without the maturity benefits.