API Lifecycle Management: Design to Retirement Guide

Most API programs are good at launching APIs. Fewer are good at ending them. A new version ships and the old one keeps answering requests. Two years later, nobody can say which consumers still depend on it or who owns the code behind it. That gap is where API lifecycle management earns its keep.

This guide is for platform leads and architects who run an API program, not a single API. It walks through each stage an API passes through, from the first contract to retirement. It spends the most time on deprecation and retirement, because those are the stages that cause the most production pain. It closes with the metrics that show whether your lifecycle is actually working, and how WSO2 API Platform tracks each stage as platform state.

What Is API Lifecycle Management?​

API lifecycle management is the structured oversight of an API from initial design through retirement. It covers how an API is designed, tested, published, versioned, deprecated, and removed, and who approves each move. It is a governance discipline as much as a technical one. Its job is to keep an API portfolio healthy as it grows.

The distinction from API management matters. API management usually refers to the runtime and consumption side: the gateway, security policies, rate limiting, and the developer portal. API lifecycle management is the layer that decides which state each API is in and what is allowed to happen next. A gateway can enforce a rate limit on a deprecated API. It takes lifecycle management to know that the API is deprecated, who still calls it, and when it is scheduled to go away.

In practice, this shows up as a set of tracked states rather than a document. An API is either in design, available for early testing, published, deprecated, or retired. Every team, from the API producers to the security reviewers, reads the same status.

The Stages of the API Lifecycle​

There is no single canonical stage count. Published frameworks range from a few broad phases to eight or more distinct stages, depending on how finely they split design, testing, security, and operations. The counts differ, but the journey underneath them is the same. This guide uses six stages: Design, Develop and Test, Publish, Version, Deprecate, and Retire.

Six stages, one loop: every stage is a tracked state with a named owner.

The loop is deliberate. Retiring an API is rarely the end of the work. What you learn from usage data and consumer migration feeds the design of the next version or the next API.

Stage	What happens	Who typically owns it
Design	The API contract is written and reviewed against organizational standards before code exists.	API producers, with an architecture or design review group
Develop and Test	The implementation is built against the contract and tested in a non-production environment.	API producers and QA
Publish	The API becomes discoverable and consumable through a developer portal or catalog.	API producers, with platform team approval
Version	Changes ship as new versions, and consumers are told what changed and why.	API producers and API product owners
Deprecate	An older version is marked for removal. Existing consumers keep working while they migrate.	API product owners and the platform team
Retire	The version is removed from service and from the active inventory.	Platform team, with sign-off from the API owner

Ownership varies by organization. What matters is that every stage has a named owner. The platform should also tell you which state each API is in without asking anyone.

Why API Lifecycle Management Matters​

The failure mode is rarely dramatic at first. Teams publish APIs faster than anyone retires them. Each new version adds another endpoint to the estate, and old versions keep running because removing them feels risky. That accumulation is API sprawl. Over time, the API portfolio contains duplicates, versions nobody has touched in years, and endpoints that no team will admit to owning.

The security cost is real. The OWASP API Security Top 10 (2023) lists Improper Inventory Management as API9. It notes that an accurate inventory of hosts and deployed API versions is needed to address problems such as deprecated versions and exposed debug endpoints. A deprecated API that still serves its existing consumers isn't a problem. That is what deprecation is for. The risk is the zombie API: an endpoint that stays reachable after everyone has forgotten it, with no owner, no support, and no review.

The consumer cost is just as concrete. When there is no defined deprecation process, removal happens ad hoc. A team shuts down an old version during a cleanup, and a partner integration breaks the same afternoon. The issue usually isn't the change itself. It's that nobody tracked who depended on the old version, or told them when it was going away.

Formal lifecycle management is worth the overhead once a few operational triggers appear:

• More than one team publishes APIs. Without shared states and standards, each team invents its own deprecation habits.
• External or partner consumers depend on your APIs. You can't coordinate a breaking change by messaging the team down the hall.
• APIs handle regulated data. Auditors will ask which versions were live, who could call them, and when they were removed.
• APIs run on more than one gateway or cloud. The inventory problem gets harder when no single system sees everything.

None of these triggers depends on a specific API count. A small portfolio with external consumers and regulated data needs more structure than a large internal one.

Design and Development: Getting the Lifecycle Right from Day One​

A well-managed lifecycle starts with a well-defined contract. In an API-first approach, the team writes the API definition before the implementation. For REST APIs that usually means an OpenAPI document. For event-driven APIs it usually means AsyncAPI. The contract becomes the single artifact that design reviews, mock servers, tests, and documentation all work from.

API definitions also give governance something to check. Naming conventions, error formats, pagination rules, security schemes, and versioning patterns can all be expressed as rules and validated automatically. Checking a contract at design time is far cheaper than finding the same problem after consumers have integrated. Once a field name is in production, changing it is a breaking change.

This is where design-time governance pays off. A typical rule set might require a security scheme on every operation and a shared schema for every error response. It might also require an owner contact in every API definition. Running those rules on each change to the contract catches drift while the fix is still a one-line edit. Teams that adopt API-first architecture tend to put these checks in the same pipeline that builds and tests the API.

Development and testing then work against that contract. The implementation is deployed to a development environment, tested against the definition, and promoted only when it matches. Contract tests are the main defense here. They fail the build when the implementation drifts from the published contract, which is the drift that most often surprises consumers later.

Publishing and Versioning APIs​

Publishing is more than deploying to a gateway. Operationally, a published API has four things. It has a running endpoint, an entry in a developer portal or API catalog, documentation consumers can act on, and a defined way to get access. An API that is deployed but not cataloged is effectively invisible. Consumers can't find it, and the platform team can't count it.

API catalogs matter for lifecycle tracking because they are where state becomes visible. A catalog maintained by hand as a wiki page tends to drift from reality within a few release cycles.

Versioning records how an API evolves, including compatible changes. Breaking changes are the ones that need a migration strategy. The mechanics vary. Teams use URI versions, header versions, or field-level deprecation, and each approach has trade-offs. From a lifecycle perspective, one rule matters most. Publishing a new major version should trigger a decision about the old one. If that decision isn't recorded as a lifecycle state change, the old version simply stays live.

Deprecating and Retiring APIs Without Breaking Consumers​

Deprecation and retirement are the stages that cause the most real-world pain, and they're the easiest to skip under deadline pressure.

Deprecation is a signal, not a removal. A deprecated API still works. Its state tells consumers that it is scheduled to go away and that they should plan to migrate. During this window, the platform's job is to keep the old version running for existing consumers while steering new consumers to the replacement.

The length of the deprecation window should depend on who the consumers are, not on a fixed number. Internal services owned by the same organization can often migrate quickly. Partner integrations and public consumers usually need much longer, because their release cycles aren't yours to control. Mobile clients that users never update may need the longest window of all. Decide the window per API, record it, and publish it with the deprecation notice.

Consumers need the signal in more than one place:

• In the API catalog, where the lifecycle state shows the API as deprecated next to its replacement.
• In the API definition, where OpenAPI's deprecated field marks individual operations.
• In the response itself. The Deprecation HTTP response header, standardized in RFC 9745, signals deprecation to a client at runtime. It can be paired with the Sunset header from RFC 8594 to announce the removal date. RFC 9745 requires that the sunset time is not earlier than the deprecation time.
• In direct communication to the owners of applications that still call the deprecated version.

Diff tooling and version strategies get fuller treatment in the guide to API versioning strategies for long-lived APIs. For lifecycle purposes, the key point is that deprecation must be a tracked state. If it lives only in a changelog, nobody can query it.

Retirement is a decision backed by evidence​

Before retiring a version, check its traffic. Which applications still call it, and how often? Zero observed traffic nominates a version for retirement. It doesn't prove the version is unused. Observe it over a window long enough to catch infrequent clients, such as monthly or quarterly batch jobs. Confirm that your telemetry covers every gateway and route that serves the version. Notify the owners of any application that has called it, and keep a rollback plan ready. If a few consumers remain, the choice is to extend the window, contact them directly, or accept the breakage knowingly. Any of those can be right. Retiring blind is not.

Retirement also has to remove the API from operational scope. Taking an API out of the catalog while the endpoint keeps answering is how zombie APIs are created. A retired API should be removed from routing, from the gateway, and from the active inventory. Its record should stay in the history, so audits can still see when it was live.

Platforms that model these states directly make the window visible to everyone. In WSO2 API Platform, for example, publishing a newer version moves the older one to a Deprecated state. Existing subscribers keep working until that version is retired.

Measuring API Lifecycle Maturity​

Lifecycle maturity is measurable. The useful metrics track whether states reflect reality and whether transitions happen on purpose. You can't manage what you can't see, so most of these start with the inventory.

• Catalog coverage: What share of the APIs actually running in your environments appears in the catalog with a lifecycle state? This is the foundation for every other metric. If APIs run on gateways the catalog doesn't know about, the number will be lower than you expect.
• Ownership coverage: What share of cataloged APIs has a named, current owner? Owners leave teams. An API whose owner has moved on is a deprecation candidate nobody will raise.
• Retirement on schedule: Of the APIs that reached their announced sunset date, how many were actually retired? Versions that stay live past their sunset date are the clearest sign that deprecation is a label rather than a process.
• Time from deprecated to retired: How long do versions sit in the deprecated state? A steadily growing number usually means retirement decisions are being avoided rather than made.
• Design-time compliance: What share of APIs pass your governance rules before publication? Trends here show whether standards are being adopted or worked around.

Track these as trends rather than targets. The right deprecation window for a public API differs from the right one for an internal service, so a single organization-wide number can mislead. What matters is direction. Catalog coverage should rise. The backlog of versions past their sunset date should shrink.

How WSO2 Operationalizes the Full API Lifecycle​

WSO2 API Platform treats lifecycle state as platform data rather than a convention teams remember. Each API proxy carries one of five lifecycle states: Created, Pre-Released, Published, Deprecated, and Retired. Changing state is a controlled action. Only users with publishing privileges can move an API between states. The console shows the current state and the allowed next transitions as a diagram. The full state model is documented in the API lifecycle management docs.

Here is how those mechanics map onto each stage, followed by how you measure them:

Design​

API proxies can be created by importing an existing API contract, including from a GitHub repository. Governance rulesets are written as Spectral YAML rule definitions and validate API artifacts, including OpenAPI and AsyncAPI definitions, API metadata, and documentation. Rulesets are defined at the organization level and attached to policies. Teams can also upload governance standards written in natural language as PDF documents, which an AI compliance analysis feature uses to evaluate APIs. The setup is described in the guide to governing API proxies.

Develop and Test​

An API proxy can be tested in a development environment before it is promoted to production. Governance policies are evaluated when API proxies are updated, so a change that breaks a rule shows up during development rather than after release.

Publish​

An API in the Created state isn't ready for consumption. Moving it to Published makes it visible in the Developer Portal and available for subscription. The Pre-Released state publishes a prototype to the Developer Portal for early consumer testing, without a full production commitment.

Version and Deprecate​

The Deprecated state is the platform's record of the deprecation window. The catalog, the console, and reviewers all read the same status, so nobody has to reconstruct it from a changelog.

Retire​

Moving a version to Retired unpublishes it and removes it from the Developer Portal. That state change alone doesn't prove every serving route is gone, including routes on federated gateways. Disable those routes explicitly where required, and verify that traffic is rejected. Because the transition is a recorded state change, retirement becomes an auditable event instead of a quiet deletion.

Measure​

Compliance results appear in a Compliance Dashboard at the organization, project, and component levels, which covers the design-time compliance metric above. The same model sits within the broader API governance program, which lists structured deprecation and retirement among its goals.

Inventory across gateways​

Catalog coverage is hardest when APIs run on more than one gateway. WSO2 API Platform supports gateway federation. You register an external gateway, discover the APIs it hosts, and bring them under the same control plane and Developer Portal. Supported third-party gateways include AWS, Azure, Kong, and Envoy. For AWS API Gateway, discovery covers REST APIs, and the discovered APIs keep running on AWS. That makes it practical to improve catalog coverage first and consolidate infrastructure later, if at all.

AI traffic under the same control plane​

Lifecycle discipline increasingly applies to more than REST APIs. The same control plane manages the AI Gateway, which governs LLM traffic through LLM proxies and agent access to tools through MCP proxies. These are separate traffic flows. Consumer applications call your APIs inbound through the API Gateway. Applications send outbound requests to LLM providers through the AI Gateway. AI agents reach MCP tools through the AI Gateway's MCP proxies. None of these is a mandatory hop in front of another. They are independent data planes managed from one control plane. Each artifact type, whether an API, an LLM proxy, or an MCP proxy, has its own documented lifecycle and policies. What they share is one governance model and one analytics view.

The platform is built on an open source foundation. One trade-off is worth naming. Lifecycle states are only as accurate as the inventory behind them. The catalog can't show APIs that were never brought into it. Teams can create or import APIs directly, and federation discovers APIs already running on other gateways. Either way, inventory coverage is part of the lifecycle work, not a separate project.

Conclusion​

API lifecycle management works when every stage is a tracked platform state, not an ad hoc process someone has to remember. Design and publication tend to get that treatment by default, because they're tied to shipping. Deprecation and retirement usually don't, and that is where sprawl, zombie APIs, and broken consumers come from.

Start with the inventory. Find out which APIs are running, who owns them, and which state each one is really in. Then make deprecation a recorded state with a published window, and make retirement a decision backed by traffic data. The metrics in this guide will show whether the process is holding.

To run that model end to end, from contract-first design through governed publication to recorded deprecation and retirement, explore WSO2 API Platform.

Frequently Asked Questions​

What's the difference between API lifecycle management and API management?​

API management covers the runtime and consumption side of APIs, including the gateway, security, rate limiting, and developer portal. API lifecycle management governs which state each API is in, from design to retirement, and controls the transitions between states.

What are the stages of the API lifecycle?​

A common six-stage model is Design, Develop and Test, Publish, Version, Deprecate, and Retire. Other frameworks use more or fewer stages, but they describe the same journey from first contract to removal.

Who manages the API lifecycle?​

API producers usually own design, development, and versioning. A central platform team typically owns the shared standards, the catalog, and the decisions to deprecate and retire, with sign-off from each API's owner.

What happens to consumers when an API is deprecated?​

A deprecated API keeps working for existing consumers. The deprecation tells them to migrate to a replacement before a stated removal date. New consumers should be directed to the replacement instead.

When should an organization formalize API lifecycle management?​

Formalize it when operational triggers appear, such as multiple teams publishing APIs, external or partner consumers, regulated data, or APIs spread across several gateways. The trigger is complexity and risk, not a specific API count.