APIM Self-Service - Onboard APIs Faster Across Defra

Overview – What is APIM Self-Service?

APIM Self-Service is an automated and standardised way for delivery teams to onboard, manage, and deploy APIs into Defra’s central Azure API Management (APIM) instance without manual DevOps or ICC intervention.

It is a Platform Engineering capability that provides teams with:

• Independence from central engineering teams
• Fast and predictable API onboarding
• Built-in guardrails that enforce compliance and platform stability
• A consistent deployment experience across DEV, TST, PRE, and PROD

In short: Delivery teams control their API lifecycle, while the platform automatically enforces governance. This allows Defra to safely scale API adoption across departments.

Why Self-Service?

Before self-service, onboarding an API required significant manual activity, including:

• Creating repository folder structures
• Writing and validating APIM policy templates
• Reviewing OpenAPI specifications
• Configuring APIM products and subscriptions
• Manually triggering deployments

As APIM usage grew, this approach became slow, risky, and unscalable. Self-service was introduced to:

• Standardise API structure and governance
• Reduce onboarding time from days to minutes
• Enforce consistent naming, security, and versioning
• Protect the shared APIM instance
• Allow teams to move independently without platform bottlenecks

APIM Self-Service is a foundational capability of Defra’s Internal Developer Platform (IDP).

How Automation Helps

APIM Self-Service is powered by: GitHub automation + API scaffolding + Azure DevOps pipelines + Git subtree sync. Together, these automate almost every step of API onboarding and deployment.

Automated Repository Scaffolding (GitHub Action)

When a developer completes input.json and runs the scaffolding workflow:

• Mandatory API folders and files are generated automatically
• Version sets, named values, products, and policy templates are created
• Environment-specific backends are scaffolded (DEV, TST, PRE, PROD)
• Naming conventions and folder hierarchy are enforced
• Manual setup is eliminated

This guarantees every API meets Defra APIM standards before any deployment occurs.

Automated Validation (GitHub Checks)

Every change is validated automatically, including:

• OpenAPI linting
• Policy validation (JWT, scopes, client IDs, issuer, etc.)
• Mandatory file checks
• Branching standards

This prevents incomplete or invalid APIs being merged or deployed.

Automated Deployment (Azure DevOps Pipelines)

Develop branch (recommended for non-prod):

• Triggers deployment to DEV
• Validation → Build → Deploy → Smoke tests
• Successful runs allow promotion to higher environments

Master branch:

• Full validation and security analysis (SonarCloud)
• Sync into the central APIM repository
• Deployment to DEV → TST → PRE → PROD (with approvals)

This ensures deployments are controlled, auditable, and repeatable.

Git Subtree Sync (Team Repos → Central Repo)

Self-service removes the historic “central repo bottleneck”. Automation:

• Pulls approved changes from team repositories
• Creates a feature branch in the central repository
• Automatically raises a Pull Request
• Enables ICC / Platform approval for production release

This provides a clear audit trail, full visibility of deployment status, and clean separation between team changes and platform publishing.

Protected Shared APIM Instance

Platform guardrails ensure:

• Policies cannot be bypassed
• Naming standards are enforced
• Backend URLs are supplied per environment
• Rate limiting and JWT configuration are validated
• Internal and external routing is applied correctly

This ensures one misconfigured API cannot impact the shared platform.

Who Owns What?

APIM Self-Service is based on clear ownership boundaries between delivery teams and the platform. This ensures teams have autonomy while maintaining platform stability and governance.

API Delivery Teams (Principal Developers / Product Teams)

Delivery teams own the API itself and are responsible for:

• Designing and maintaining the API specification (OpenAPI / Swagger)
• Implementing and updating API policies, including JWT validation, rate limiting values, headers and transformations
• Providing correct backend URLs per environment
• Managing API versioning and lifecycle decisions
• Raising pull requests and following the agreed branching strategy
• Validating API behaviour in DEV and TST
• Fixing validation, policy, or deployment failures
• Requesting deviations when standard patterns do not meet requirements

Platform Engineering (Self-Service Platform Owners)

Platform Engineering owns the self-service framework and automation, including:

• Self-service design and standards
• GitHub scaffolding workflows
• Validation rules and guardrails
• Azure DevOps pipeline templates
• Git subtree sync logic
• Environment promotion workflows
• Security baseline policies
• Shared APIM capacity protection
• Evolving platform logic to support validated new use cases

ICC / APIM Operations Team

The ICC / APIM Operations team owns the shared APIM service and production governance, including:

• Central APIM instance configuration
• APIM infrastructure stability and limits
• Production approvals and release governance
• Reviewing requests for non-standard patterns
• Coordinating platform changes across environments
• Responding to platform-level incidents

Governance Overview

Key Principle: Self-service does not remove governance, it automates it. Ownership is distributed, but responsibility is explicit.

References

• Principal Developers Onboarding Guide (opens in new tab) — Note: This guide is the primary operational reference for teams onboarding or updating APIs.
• APIM API Onboarding & Approval Workflow Diagram (opens in new tab) — A detailed end-to-end workflow diagram showing how API changes flow from team repositories into the central APIM instance.