Enterprise API Governance and Runtime Health

Challenge

A large enterprise API estate was operating across multiple Azure API Management environments, with APIs exposed through Experience, Process, and System layers.

As the estate grew, several operational challenges emerged:

• API revisions and versions needed to move consistently through DEV, QA, and PROD.
• API specifications, policies, fragments, and environment configuration needed to remain synchronized with source control.
• Backend services exposed different health models, while consumers required stable and predictable health endpoints.
• Endpoint retirement, deprecation, new revisions, and contract updates needed to be introduced without disrupting existing consumers.
• Manual APIM changes created a risk of configuration drift between deployed APIs and repository state.
• Teams needed clearer governance around API promotion, reusable policies, health probes, versioning, and deployment ownership.

Approach

Kindl Labs helped establish a source-controlled API governance and delivery model around Azure API Management.

The work focused on treating APIs, policies, revisions, and shared APIM components as governed engineering artifacts rather than portal-only configuration. The model addressed the full change lifecycle: contract design, validation, environment promotion, runtime operation, deprecation, recovery, and ownership.

Key elements included:

1. API versioning and revision governance

• Used versions for intentional contract evolution and revisions for controlled, non-breaking implementation changes.
• Defined how a candidate revision became current, how an existing revision remained available during verification, and how teams could return to a known state.
• Treated retirement and deprecation as explicit lifecycle states with predictable response behaviour rather than ad hoc endpoint removal.
• Preserved existing consumer contracts while new capabilities moved through their own validation and release path.

2. Source-controlled APIM configuration

• Maintained API specifications, operation-level controls, API-level controls, revisions, and environment configuration together with the delivery definition.
• Made reviewed repository state the release baseline, reducing ambiguity about whether the portal or the repository represented the intended configuration.
• Separated portable API artifacts from environment-specific values so the same governed definition could move between DEV, QA, and PROD.

3. Automated APIM promotion

• Used a centralized publishing workflow to deploy approved API artifacts into Azure API Management.
• Separated contract validation from publishing authority, ensuring that syntax and structural checks could complete before an environment was changed.
• Established one repeatable promotion path rather than allowing each API team to implement deployment mechanics independently.
• Reduced direct portal changes and made exceptional changes visible, reviewable, and recoverable.

4. Reusable policy fragments

• Extracted common controls for health probes, response handling, deprecation, retirement, and multipart request processing.
• Kept shared behaviour centrally maintainable while preserving API-level and operation-level ownership where behaviour genuinely differed.
• Avoided copying complex policy logic across APIs, where small variations would otherwise become difficult to review and support.

5. Runtime health abstraction

• Introduced a stable consumer-facing health contract while allowing services to retain their own operational probe model.
• Used APIM as the boundary between the public health contract and service-specific runtime implementation.
• Kept routing and response normalization in the gateway so monitoring integrations did not need to change when an underlying service changed its probe paths or payload shape.

6. Layered API architecture

• Maintained clear responsibilities across Experience, Process, and System APIs.
• Kept channel-facing contracts in the Experience layer, orchestration in the Process layer, and system-specific capabilities in the System layer.
• Prevented backend topology and implementation details from leaking into consumer contracts, reducing coupling and limiting the blast radius of service changes.

7. Controlled change and recovery
   • Used feature branches, API revisions, extraction, and publishing workflows to introduce and validate changes incrementally.

• Preserved a reviewable history of API and gateway evolution, including the configuration required to reconstruct a known release.
• Designed recovery around republishing an approved state instead of manually recreating portal configuration under incident pressure.

Governance Model

The operating model made ownership explicit. API teams remained accountable for contracts and API-specific behaviour. The platform capability owned shared gateway controls, publishing mechanics, and environment conventions. Release approval remained distinct from the technical act of publishing.

Every change therefore had a defined path through contract review, policy validation, revision selection, environment promotion, and post-deployment verification. Changes that affected consumers, such as a new version or endpoint retirement, were handled differently from internal implementation changes that could be introduced through a revision.

This distinction matters in a large estate. Without it, technically valid changes can still create operational risk through inconsistent promotion order, unclear ownership, or untracked portal edits. The governance model provided common controls without forcing every API to share the same release cadence.

Solution Architecture

The runtime path moves from API consumers through Experience APIs in Azure API Management, then through Process and System APIs to backend services. A separate delivery path takes governed repository artifacts through validation and a central publishing workflow into DEV, QA, and PROD. This separates runtime responsibility from configuration delivery while preserving traceability between them.

Runtime health follows a stable consumer and monitoring contract. Shared gateway logic maps the stable APIM /health endpoint to service-specific operational probes without exposing those implementation details to consumers.

Engineering Decisions

Contract and deployment concerns were separated. An OpenAPI definition could be validated independently of publishing permissions. This allowed contract feedback to happen early while keeping changes to shared APIM environments behind a controlled release boundary.

Environment differences were configuration, not forks. API definitions and shared controls followed one promotion path, with environment-specific values supplied at publication time. This reduced the chance that QA and PROD represented materially different gateway definitions.

Gateway configuration remained declarative and recoverable. The intended state could be reviewed before deployment and reapplied when recovery was required. Portal access remained an operational capability, not the normal authoring model.

Change type determined the release mechanism. Revisions supported controlled implementation evolution within an existing contract. Versions represented deliberate contract change. Deprecation and retirement were governed transitions with explicit consumer behaviour rather than immediate deletion.

Shared controls had bounded ownership. Cross-cutting behaviour was centralized only when it was genuinely common. API-specific logic stayed close to the owning API, avoiding a global policy layer that would become difficult to reason about or change safely.

Health was treated as a contract. Consumers and monitoring systems received a stable endpoint and response expectation. Service teams could evolve operational probes independently, while the gateway absorbed the mapping and normalization responsibility.

Outcome

The approach created a more controlled and maintainable enterprise API platform.

Key outcomes:

• Established source-controlled governance for API contracts, policies, revisions, and APIM configuration.
• Reduced configuration drift between Git and deployed Azure API Management environments.
• Standardized API promotion across environments.
• Enabled reusable governance patterns through shared APIM policy fragments.
• Allowed API versions and revisions to evolve without unnecessarily disrupting existing consumers.
• Provided stable runtime health contracts while keeping backend health implementation independently evolvable.
• Improved traceability and recoverability of API changes.
• Reduced dependence on manual APIM portal configuration.
• Created a repeatable foundation for onboarding and governing additional enterprise APIs.

The result was not only a deployment workflow. It was an operating model for a shared enterprise platform: teams had clearer boundaries, release decisions had an auditable path, and the deployed gateway could be reconciled with an approved source state. New APIs could adopt the same lifecycle without reproducing the governance design for each onboarding.

API contracts, policies, revisions, runtime health, and promotion were brought under a consistent source-controlled governance model, creating a repeatable foundation for operating a growing enterprise API estate.

Technologies

• Azure API Management
• OpenAPI
• REST APIs
• APIM Policies
• YAML Workflows
• API Versioning
• API Revisions
• OAuth 2.0