Integration / API
APIExternalIntegration Pattern

Int-API-External

Problem

An internal application needs to synchronously exchange data or services with an external user, partner, or system in real-time.

Solution

For inbound requests, utilize an External API Gateway deployed at the Public Subnet (Perimeter) to secure, proxy, and govern connections from external systems to the internal application. For outbound requests (internal to external), route traffic through a designated secure egress point (such as a Forward Proxy or Egress Gateway) to control, filter, and log outbound connectivity.

Cloud Paradigm

API-First Design, API-Led Connectivity, Edge Security (Ingress/Egress control), and Zero Trust Architecture.

Implementation Guidelines

Solution Flow

Inbound Flow (External Consumption):

  1. External Caller: A third-party client initiates an HTTPS request over the public internet.
  2. Edge Protection (WAF): The traffic hits a public-facing cloud edge where a Web Application Firewall inspects for malicious signatures (e.g., OWASP Top 10) and enforces rate limits.
  3. API Gateway: The sanitized request reaches the API Gateway, which authenticates the caller (e.g., OAuth 2.0 / OIDC), terminates TLS, and routes the traffic to the private subnet.
  4. Backend Workload: The internal microservice receives the request, processes the business logic, and returns the response.

Outbound Flow (Internal Egress):

  1. Backend Workload: The internal service initiates a secure HTTPS request to a partner API.
  2. Egress Gateway / NAT: Because the workload sits in a private subnet with no direct Public Internet access, the traffic routes through a Managed NAT/Egress Gateway. This gateway enforces outbound FQDN whitelisting and performs network address translation.
  3. External Target: The partner system receives the request originating from a static, whitelisted cloud egress IP.

Additional Details

  • Protocol & Format: The backend workload providing the API endpoint should use modern synchronous protocols (REST, GraphQL, or gRPC) or legacy protocols (SOAP) over HTTPS. Use standard data formats such as JSON, XML, or Protobuf.

  • API Design & Documentation: Describe the API using standard machine-readable specifications (e.g., OpenAPI Specification/Swagger, WSDL). Information objects exchanged must be based on a common vocabulary or industry-standard data models.

  • API Management & Lifecycle: Implement a strict versioning strategy (e.g., URI or Header-based) for inbound APIs to avoid breaking changes for external consumers. Treat API Gateway configurations as code (IaC/GitOps) deployed via CI/CD pipelines.

  • Pattern Delegation: If the APIs exposed by the provider system require complex data transformations, protocol translation, or multi-step orchestration, delegate these responsibilities to the Middleware-External pattern rather than building complex logic into the API Gateway.

  • Outbound Rules: If the internal application initiates the connection, it must not possess direct Public Internet access. The outbound connection must be routed through a highly available Egress Gateway or NAT gateway for centralized egress filtering.

  • Observability: Enable centralized logging, metrics (latency, error rates, traffic), and distributed tracing (e.g., OpenTelemetry) on both the API Gateway and Egress Gateway to track cross-boundary request lifecycles.

Security Controls

  • Perimeter Security: Inbound connections must terminate at an Edge API Gateway within a public subnet or dedicated ingress VPC. Protect the Gateway with a Web Application Firewall (WAF) to mitigate common vulnerabilities (e.g., OWASP Top 10) and malicious bot traffic.

  • Transport Security: Enforce strict Transport Layer Security (TLS 1.2 or higher) on all inbound and outbound endpoints.

  • Authentication & Authorisation:

    • For system-to-system (B2B) integrations, authenticate consumers using OAuth 2.0 (Client Credentials Grant) or Mutual TLS (mTLS).

    • For external user connections, use OAuth 2.0/OpenID Connect (OIDC).

    • Note: API Keys should only be used for basic identification or quota management, not as a primary authentication mechanism.

  • Traffic Management: Use API Management policies to enforce rate limiting, throttling, and burst quotas to protect the backend workloads from DDoS attacks or accidental traffic spikes.

  • Outbound Controls: Configure the Egress Gateway and egress firewalls to allow outbound connections only to explicitly whitelisted external IP addresses or fully qualified domain names (FQDNs). Inspect outbound traffic for Data Loss Prevention (DLP) if required by compliance.