CH09-06: API Platform Architecture Scenario

Goal

This section applies the Chapter 9 model to a realistic API platform. The goal is not to produce one perfect reference architecture. The goal is to show how consumer contracts, gateway controls, backend ownership, integration, observability, governance, availability, and cost fit together.

The scenario is a retailer exposing product, order, and customer APIs to a web app, mobile app, partner fulfillment provider, and internal support dashboard.

The durable idea is:

A strong API platform design explains how consumers safely reach backend capabilities through governed contracts.

The Scenario

The retailer has several consumer types:

• A public web application for shoppers.

• A mobile application with slower client upgrade cycles.

• A partner fulfillment provider that needs order and shipment APIs.

• An internal support dashboard used by employees.

The retailer exposes three main API groups:

• Product APIs for catalog search and product details.

• Order APIs for order creation, status, and fulfillment updates.

• Customer APIs for profile and support workflows.

The platform requirements are practical:

• Consumers should not call backend services directly.

• Public, mobile, partner, and internal consumers need different policies.

• Authentication and authorization must be explicit.

• Partners need subscriptions, rate limits, and auditability.

• Mobile clients need careful versioning and deprecation.

• Order creation should not synchronously complete every downstream fulfillment step.

• Teams need gateway, backend, dependency, and consumer-level visibility.

• Cost should be attributable by API product, environment, and owning team where possible.

Step 1: Start with the Contract Path

Before naming services, walk the path:

Consumers
  -> API contract boundary
  -> Product, order, and customer APIs
  -> Data stores and integration services
  -> Observability, governance, ownership, and cost controls

This prevents a common mistake: starting with backend routes and only later discovering that partners, mobile clients, and internal support users need different contracts.

Step 2: Choose a First-Pass Azure Design

A reasonable first-pass design might look like this:

flowchart LR
    WEB["Web app"]
    MOB["Mobile app"]
    PART["Partner fulfillment"]
    INT["Internal support"]
    APIM["Azure API Management<br/><small>Products, policies, versions, telemetry</small>"]
    ID["Microsoft Entra ID<br/><small>Users, apps, workload identities</small>"]
    PROD["Product API<br/><small>App Service or Container Apps</small>"]
    ORD["Order API<br/><small>App Service or Container Apps</small>"]
    CUST["Customer API<br/><small>App Service or Container Apps</small>"]
    SQL["Azure SQL Database<br/><small>Orders and customers</small>"]
    COSMOS["Cosmos DB or search store<br/><small>Catalog read model</small>"]
    BUS["Service Bus<br/><small>Fulfillment work</small>"]
    MON["Azure Monitor + Application Insights"]
    GOV["Owners, versions, budgets"]

    WEB --> APIM
    MOB --> APIM
    PART --> APIM
    INT --> APIM
    APIM --> ID
    APIM --> PROD
    APIM --> ORD
    APIM --> CUST
    PROD --> COSMOS
    ORD --> SQL
    ORD --> BUS
    CUST --> SQL
    APIM --> MON
    PROD --> MON
    ORD --> MON
    CUST --> MON
    SQL --> MON
    COSMOS --> MON
    BUS --> MON
    APIM --> GOV

This diagram is intentionally compact. A real design would include networking, private endpoints, DNS, CI/CD, identity app registrations, alert rules, and environment separation. The teaching point is the responsibility path.

Step 3: Assign Platform Responsibilities

The design does not make API Management responsible for everything. It makes API Management responsible for the boundary.

Step 4: Shape the Consumer Contracts

Each consumer receives a contract that matches its risk and operating model.

This prevents the platform from exposing one broad API surface to everyone. Consumers see the contracts they need, with the controls they require.

Step 5: Place Backends Behind the Boundary

The backend services should align to business capability and ownership.

Product APIs may read from a catalog store or search-optimized read model. Order APIs may use Azure SQL for order state and Service Bus for fulfillment messages. Customer APIs may use relational data and strict authorization rules. Each backend service owns its business behavior and data access.

The backend services should also use secure dependency patterns:

• Managed identities where supported.

• Key Vault for unavoidable secrets, certificates, or external provider keys.

• Private endpoints and private DNS where dependencies should avoid public exposure.

• Least-privilege database and storage access.

• Diagnostic logs and dependency telemetry.

The API gateway should not directly manipulate order tables or customer records. It should route the request to the backend that owns that behavior.

Step 6: Decide What Becomes Asynchronous

Order creation is a useful example.

The API can synchronously validate the request and create the initial order record. It should not necessarily call every fulfillment, inventory, notification, and partner system before responding. That would make the API slower and more fragile.

A better pattern may be:

Order API request
  -> Validate caller and request
  -> Create order record
  -> Publish fulfillment message to Service Bus
  -> Return accepted or created response
  -> Worker processes fulfillment asynchronously

This design needs idempotency, message contracts, retry handling, dead-letter monitoring, and user-facing status behavior. The trade-off is worthwhile when downstream work should be durable and decoupled from the immediate API response.

Step 7: Operate the Platform

A complete design includes operations from the beginning.

For observability, track:

• Gateway request volume, latency, authentication failures, policy failures, and throttling.

• API errors and backend latency by operation and version.

• Dependency latency for Azure SQL, Cosmos DB, Storage, and Service Bus.

• Partner traffic and retry patterns.

• Mobile client version usage.

• Deprecated API calls.

• Cost by gateway, backend, data, messaging, and logging.

For governance, define:

• Who owns each API product.

• Who can approve partner access.

• Who owns policy exceptions.

• How versions are introduced and retired.

• How consumers are notified about breaking changes.

• Who responds to gateway, backend, and dependency alerts.

This is where the API platform becomes a product, not just infrastructure.

Important Alternatives

Public or Internal APIs

Some APIs may be public or partner-facing. Others may be internal-only. Do not force every API into the same exposure model.

Public and partner APIs usually need stricter onboarding, WAF or edge considerations where relevant, stronger traffic controls, and clearer documentation. Internal APIs may rely more on private networking and employee or workload identity, but they still need contracts, versions, and monitoring.

App Service, Container Apps, or AKS

App Service is a strong fit for many managed API backends. Container Apps fits containerized APIs and workers when the team wants managed container hosting. AKS fits when Kubernetes control, ecosystem, or platform standards are required.

Do not choose AKS only because the API is important. Importance does not automatically mean Kubernetes.

Centralized or Team-Owned Policies

Some policies should be centralized, such as baseline authentication, correlation IDs, logging expectations, and partner rate-limit standards. Other policies may need team ownership, such as API-specific transformations, version routing, or product-specific quotas.

The platform should provide guardrails without blocking safe team delivery.

Common Mistakes

• Exposing backend services directly without a contract boundary.

• Centralizing so much control that backend teams cannot deliver safely.

• Ignoring versioning, monitoring, incident ownership, and cost allocation.

• Making partner APIs too broad because they reuse internal endpoints.

• Treating Service Bus as an afterthought instead of designing asynchronous contracts clearly.

• Assuming API Management removes the need for backend authorization and data protection.

If Someone Asks You

How would you design an Azure API platform?

A good answer is:

I would start with consumer contracts. Web, mobile, partner, and internal consumers should reach backend capabilities through Azure API Management, where products, policies, versions, rate limits, routing, subscriptions, and telemetry are managed. Backend services should run on App Service, Container Apps, AKS, Functions, or another compute option based on workload shape, and they should own business logic and data integrity. Data access should use managed identities, Key Vault where needed, private access where required, and least privilege. Long-running or unreliable downstream work should use durable messaging such as Service Bus. The platform also needs observability, ownership, version lifecycle rules, availability design, and cost controls.

What You Should Remember

Walk from consumer contract to gateway controls to backend responsibility to operations.

Questions to Check Your Understanding

1. Which responsibilities belong at API Management?

2. Which responsibilities belong to backend teams?

3. How does the design support visibility and safe change?

4. Why might order fulfillment use Service Bus behind an API?