Governance Policies Integration API Patterns - Azure/az-prototype GitHub Wiki

API Patterns

Governance policies for Api Patterns

Domain: integration

Patterns

Name Description
Versioned API with APIM version sets URL path-segmented API versioning with sunset headers on deprecated versions
JWT-validated API with Entra ID APIM inbound JWT validation using Entra ID OpenID Connect discovery
OpenAPI-driven API with request validation API imported from OpenAPI spec with inbound content and parameter validation

Anti-Patterns

Description Instead
Do not deploy APIs without versioning Use APIM API version sets with URL segment versioning (v1, v2)
Do not deploy APIs without authentication Configure validate-jwt policy with Entra ID OpenID Connect discovery
Do not skip request validation Use validate-content and validate-parameters policies with OpenAPI schema enforcement
Do not expose internal error details in API responses Use on-error policy to return RFC 9457 Problem Details format

References

Checks (4)

Check Severity Description
CC-INT-API-001 Required Implement API versioning using URL path segments in APIM with version sets
CC-INT-API-002 Required Configure OAuth 2.0 / JWT validation in APIM inbound policies for all API endpoints
CC-INT-API-003 Required Configure request and response validation policies in APIM to enforce API contracts
CC-INT-API-004 Recommended Integrate OpenAPI specification with APIM for auto-generated documentation and developer portal

CC-INT-API-001

Implement API versioning using URL path segments in APIM with version sets

Severity: Required
Rationale: API versioning prevents breaking changes for existing consumers; URL path versioning is the most discoverable approach
Agents: cloud-architect, terraform-agent, bicep-agent, app-developer, csharp-developer, python-developer

Targets

  • Microsoft.ApiManagement/service
  • Microsoft.Web/sites
  • Microsoft.App/containerApps

Companion Resources

Resource Name Purpose
Microsoft.ApiManagement/service/apiVersionSets api-version-set API version set grouping related API versions under a single path
Microsoft.ApiManagement/service/apis/policies deprecation-policy Outbound policy adding Sunset and Deprecation headers to deprecated API versions

CC-INT-API-002

Configure OAuth 2.0 / JWT validation in APIM inbound policies for all API endpoints

Severity: Required
Rationale: APIs without authentication allow unrestricted access; JWT validation at the gateway prevents unauthorized requests from reaching backends
Agents: cloud-architect, terraform-agent, bicep-agent, app-developer, csharp-developer, python-developer

Targets

  • Microsoft.ApiManagement/service
  • Microsoft.Web/sites
  • Microsoft.App/containerApps

Companion Resources

Resource Name Purpose
Microsoft.ApiManagement/service/authorizationServers entra-id-oauth OAuth 2.0 authorization server for Entra ID integration in developer portal

CC-INT-API-003

Configure request and response validation policies in APIM to enforce API contracts

Severity: Required
Rationale: Request validation prevents malformed input from reaching backends; response validation ensures API contract compliance
Agents: cloud-architect, terraform-agent, bicep-agent, app-developer, csharp-developer, python-developer

Targets

  • Microsoft.ApiManagement/service
  • Microsoft.Web/sites
  • Microsoft.App/containerApps

CC-INT-API-004

Integrate OpenAPI specification with APIM for auto-generated documentation and developer portal

Severity: Recommended
Rationale: OpenAPI specs provide machine-readable API contracts; APIM developer portal auto-generates interactive documentation
Agents: cloud-architect, terraform-agent, bicep-agent, app-developer, csharp-developer, python-developer

Targets

  • Microsoft.ApiManagement/service
  • Microsoft.Web/sites
  • Microsoft.App/containerApps
⚠️ **GitHub.com Fallback** ⚠️