Implementation roadmap

Each phase is independently useful, SDK-witnessed, documented, and reflected in the parity ledger. Full parity is a moving target; upstream audits append work without erasing completed evidence.

P0 - Contract spike and foundations

Goal: prove the architecture before broad resource work.

• Go module, command, config, controllable clock, request IDs, SQLite migrations, TLS, and host routing.
• Embeddable pkg/emulator test fixture with isolated state, HTTP/TLS modes, trusted client, lifecycle cleanup, and configuration options.
• ARM auth against entra-emulator and canonical ARM errors for the implemented resources.
• Pre-seeded service plus full service GET/PUT/PATCH/DELETE/list semantics. The complete stable 2024-05-01 document is retained losslessly; resource-group/subscription lists, recursive PATCH, idempotent deletion, create/update status, body ETags, deterministic LRO polling, a dated schema inventory, and a read-only differential harness are working. An authorized live Azure fixture remains before external verification.
• Minimal API, operation, policy, product, product/API link, and subscription resources.
• Four-SDK custom-endpoint spike: Go armapimanagement v1.1.1, JavaScript @azure/arm-apimanagement 10.0.0, Python azure-mgmt-apimanagement 5.0.0, and .NET Azure.ResourceManager.ApiManagement 1.3.1.
• HTTP route to fixture backend, subscription-key validation, forward-request, set-header, and return-response.
• Policy XML round-trip, immutable snapshot compiler, last-known-good failed-compile protection, and bounded structured gateway traces.
• CI, 100% coverage gate, GoReleaser skeleton, non-root distroless container, Compose, and initial MkDocs site.

Exit: every SDK creates/configures a service and a subscription-protected API, then calls it through the gateway with Entra-authenticated management.

Exit workflow status: the Go, JavaScript, Python, and .NET SDKs all configure the service, API, operation, and API-scoped subscription and call the protected gateway. The Go witness additionally covers real Entra-issued management tokens; equivalent Entra credentials for the other language witnesses remain part of the identity expansion.

P1 - Core management and HTTP gateway

• APIs, revisions, releases, versions, operations, schemas, tags, products, groups, users, subscriptions, named values, backends, certificates, fragments, loggers, and diagnostics for stable API versions. APIs, operations, schemas, releases, products, groups, users, subscriptions, named values, backends, caches, identity providers, OpenID Connect providers, OAuth authorization servers, documentation, certificates, loggers, diagnostics, API version sets, tags, and policy fragments now have canonical lossless documents; user/subscription/named-value/certificate/logger/cache/identity-provider/OpenID-Connect-provider/authorization-server documents enforce store-level secret redaction, recursive PATCH is implemented where the stable surface exposes PATCH, and the same persistence pattern remains to be extended across other core resources.
• OpenAPI import/export and linked imports.
• Complete ARM common semantics: ETags, paging, filters, patch, LROs, errors, and secret operations. Conditional ETag evaluation, stable-contract required If-Match enforcement for implemented entity mutations, common collection paging/filter grammar, undocumented OData-option rejection, policy-fragment $orderby=name, the stable scalar field/operator/function matrix for every implemented collection shape, named-value tags/any(...)/tags/all(...) predicates, selector availability/boolean validation, association-backed product tag filtering, tag scope filtering, Key Vault refresh-failure projection, and API/version-set/tag/product/user expansion projections are implemented centrally; the remaining semantics are still open.
• HTTP routing edge cases, custom domains, backend TLS, pools, retries, circuit breakers, streaming, SSE, and WebSocket. Custom hostname routing from persisted hostnameConfigurations, explicit publicNetworkAccess=Disabled ingress rejection, backend TLS chain-validation/client-certificate behavior, backend retry execution for transient failures/status predicates, circuit-breaker state, SSE flushing, and WebSocket upgrade tunneling are implemented; private endpoint topology and certificate lifecycle remain open.
• Entra JWT, managed identity, OAuth/OIDC, client certificates, and Key Vault-backed named values. Named-value and certificate refreshSecret/PUT now retrieve versioned and versionless secrets from a Key Vault data-plane endpoint, persist classified last-known-good lastStatus, and project isKeyVaultRefreshFailed; a 401 WWW-Authenticate Bearer challenge acquires a managed-identity token and retries once, leaving last-known-good values on failure.
• Core policy families: routing, mutation, control flow, auth, limits, cache, validation, send-request, transforms, and tracing. Literal and expression-evaluated query/body/variable/method/header mutations, CORS response/preflight handling, check-header, validate-jwt backed by the configured Entra validator with audience/issuer/required-claim payload checks, ip-filter validation, injected send-request calls, deterministic rate-limit/quota and keyed windows with nested api/operation children and quota bandwidth, keyed limit-concurrency slots, first-class sequential wait under limit-concurrency and retry, response and value cache lookup/store/removal with gateway TTL integration, validate-status-code, validate-content, validate-headers, validate-parameters, validate-client-certificate, choose control flow, trace events, authentication-basic, authentication-managed-identity, authentication-oauth2, authentication-certificate, find-and-replace, json-to-xml, xml-to-json, jsonp transforms, standalone set-status, mock-response including example bodies, compile-time include-fragment expansion, fire-and-forget send-one-way-request, configured-validator validate-azure-ad-token with client-application-ids and required-claims, Adobe cross-domain XML, and gateway/backend redirect-content-urls are implemented; schema mock bodies, openid-config, inline token-value, and the remaining families are still open.
• Operator portal for resources, snapshots, traces, clock, faults, and parity. The embedded operator portal now exposes runtime status, active snapshot, parity status, trace navigation, controllable clock state, persisted service/API/core-resource summaries, resource and policy editors with secret/material redaction, and deterministic backend fault controls under /_emulator/portal/; service-to-API fallback, API <base/> composition, operation-level composition, product subscription composition using the matching operation plan, and ARM GET/PUT for service/API/operation/product policies are implemented, while workspace inheritance remains open.

Exit: common APIM application-development and CI workflows run offline with official SDKs and documented policies.

P2 - Expression completeness and policy inventory

• Full documented C# 7 expression grammar used by APIM. The value model, lexer, evaluator, and context binder for literals, grouping, arithmetic, string concatenation, comparisons, boolean short-circuit, ternary, identifiers, member access, calls, indexing, and statement blocks with expression-scoped var locals, if/else, and a required return on every path are implemented for choose, mutation policies, retry conditions, send-request fields, send-one-way-request mode/timeout, set-backend-service, rewrite-uri, find-and-replace from/to, value-cache key/value fields, cache-lookup-value variable-name, CORS allowed-origins/allowed-methods/allowed-headers/expose-headers/max-age, check-header name/values/error message, limit-concurrency key, rate-limit/quota counter-key, authentication-basic/managed-identity/oauth2/certificate attributes, set-status code/reason, mock-response status-code/content-type, json-to-xml root-element-name, jsonp callback-parameter-name, and validate-azure-ad-token tenant-id/header-name/query-parameter-name/failed-validation-httpcode/failed-validation-error-message, including request URL stringification, Url.Port, Headers.Get, request/response Body.AsString(), response status/headers, last-error message on retry and via stateEnv for on-error/choose, and snapshot-backed context.Api/Operation/Product/Subscription/User/Deployment scalars; the binder allowlist is checked in and table-tested so new host members cannot land unbound; other statements, remaining context members, and other expression-bearing fields remain open.
• Complete APIM context object and documented allowed .NET type/member surface in pure Go.
• Multi-statement blocks, lambdas/LINQ, JSON/XML/JWT/crypto semantics, and exception behavior.
• Every policy-reference entry implemented or carrying an explicit external dependency adapter. The checked-in Learn catalog is fully classified (implemented / partial / unsupported / external-adapter) and CI rejects unclassified names and compiler drift; remaining families still need implementations or adapters.
• Scope inheritance across service, product, API, operation, fragments, and workspace governance.
• Generated member- and policy-level compatibility documentation.
• Large Azure differential corpus for error paths and edge semantics.

Exit: policy and expression inventories contain no unclassified stable entries.

P3 - Developer portal

• Portal content/item APIs, draft model, publishing, revisions, reset, and media.
• APIM-compatible consumer portal with API/product docs, search, visibility, subscriptions, profile, and reports.
• Basic, Entra, external identity, invitation, password reset, and delegated authentication flows.
• Interactive REST/SOAP/GraphQL/WebSocket console with subscription and OAuth support.
• Administrative editor, styles, layouts, widgets, custom widgets, CSP, localization, accessibility, and custom domains.
• Self-hosted portal interoperability and published content export/import.

Exit: publisher and consumer portal journeys match Azure fixtures and use the same underlying APIM resources as the gateway.

P4 - Workspaces and distributed gateways

• Workspace resource hierarchy, uniqueness, references, RBAC, deletion, and service governance.
• Dedicated/shared/default workspace gateway association and runtime isolation. Self-hosted gateway registration, API association, hostnames and per-gateway certificate-authority trust are implemented, with hostname-routed runtime isolation and documented key/token issuance; workspace gateways (the top-level Microsoft.ApiManagement/gateways resource) remain open.
• Separate-process self-hosted gateways, configuration sync, auth/token rotation, backup, last-known-good, heartbeat, metrics, disconnected and fail-static behavior. The configuration-sync payload is proprietary and uncaptured, so it is not emulated and no real self-hosted gateway container has connected to this emulator.
• Gateway capability/version matrix and Arc-visible management contracts.
• Federated workspace diagnostics and unified developer portal discovery.

Exit: multi-team workspace and hybrid gateway scenarios pass SDK, failure, and differential suites.

P5 - SOAP, GraphQL, gRPC, and advanced protocols

• WSDL/SOAP import, pass-through, transformations, SOAP actions, and faults.
• Pass-through and synthetic GraphQL, resolver policies, validation, limits, and introspection.
• gRPC unary/streaming, protobuf imports, metadata, status/trailers, deadlines, and tier constraints.
• Complete WebSocket/SSE behavior and protocol-specific telemetry.
• OData/WADL compatibility retained where publicly supported.

Exit: each documented protocol has real-client witnesses and Azure differential fixtures.

P6 - Networking, tiers, regions, and platform lifecycle

• All current tiers/SKUs and capability validation.
• Classic/v2 networking, public access, inbound private endpoints, outbound integration/injection, DNS, IP state, proxy, zones, regions, and multi-region routing.
• Custom hostname/certificate lifecycle for gateway, portal, management, SCM, and configuration endpoints.
• Backup/restore, deleted services, upgrades/migrations, scaling, deployment state, and long infrastructure LRO simulation.
• Local topology profiles that make network state behaviorally testable.

Exit: stable infrastructure-facing management contracts and locally observable network outcomes are parity-classified and differential-tested.

P7 - Observability, authorizations, and ecosystem integrations

• Azure Monitor schema, diagnostics settings, resource logs, metrics, analytics, and reports. Local gateway events now capture request/response bodies up to configured byte limits with the same secret masking as headers; Azure differential remains open.
• Application Insights and OpenTelemetry correlations, sampling, masking, and exporters.
• Authorization providers, credential manager, Service Bus, Event Hub-style logging, Dapr, Service Fabric, external cache, and documented backend integrations.
• Notifications, email templates, issues/comments, tenant settings, reports, and remaining platform resources.

Exit: the stable management operation inventory is fully verified or has an explicit external-adapter test fixture.

P8 - AI gateway, MCP, and current previews

• Model APIs and provider adapters, load balancing, token limits, semantic cache, content safety, prompt controls, logging, and model telemetry. Token limits and token metrics are implemented for both the llm-* and azure-openai-* policy names, streamed answers included; the counts are exact when they come from the model’s own usage object and approximate when estimate-prompt-tokens forces a decision before the model has answered.
• MCP-related import, exposure, governance, authentication, policy, and portal behavior. Exposure is implemented: an API declared type: mcp is published as an MCP server over the Streamable HTTP transport and its operations are its tools, with schemas derived from the parameters they already declare. Passthrough is implemented too: an API declared mcpMode: passthrough forwards every JSON-RPC message to an upstream MCP server rather than interpreting it, so the upstream is never capped at what this emulator understands. Resources and prompts, per-tool policy scoping, and the older SSE transport remain open.
• Deterministic fake providers plus opt-in Azure/OpenAI/provider differential suites.
• Promote supported preview contracts only after stable tracks remain green.

Exit: all publicly documented stable AI/MCP capabilities are parity-classified; previews have isolated versioned coverage.

P9 - Full-parity audit and continuous maintenance

• Zero unknown stable operations, policies, expression members, portal workflows, gateway capabilities, or tier rows.
• Cross-region/tier differential sweep and reproducible parity release snapshot.
• Performance and memory budgets published for idle, routing, policies, portal, self-hosted gateway, and load scenarios.
• Automated upstream spec/docs/release-note diff opens parity work items.
• Deprecation policy and compatibility windows for older SDK/API versions.

Exit: a release may claim full parity only for the exact dated compatibility snapshot whose evidence is published. Later upstream changes reopen the ledger.