External API

Origin & evolution

The discipline for living with foreign interfaces was sharpened by Eric Evans in Domain-Driven Design (2003) through the anti-corruption layer. When a system integrates with another that does not share its semantics, Evans argued for a translation layer between them so that the external model's concepts do not leak in and corrupt the local domain. Microsoft's pattern catalogue restates it as a façade plus adapter plus translator that isolates a bounded context🔲Bounded ContextEngineeringA DDD bounded context defining a service boundaryView reference → from an external system, so that replacing or upgrading the dependency touches only the layer, never the core.

Practice has caught up with the warning. Public APIs are now governed by explicit version policies, deprecation windows, and rate limits, and the operational reality is that the vendor's roadmap🛣️RoadmapProduct SpecificationA strategic plan of features and milestonesView reference → is not yours. A breaking change on their side, a quota you exceed during a launch, or a region outage all land as your incident🚨IncidentDevOps & PlatformA production incidentView reference →. The anti-corruption layer endures because it localises that blast radius to one translatable seam.

How it works in practice

A subscription🔂SubscriptionSales & RevenueA recurring subscriptionView reference → product integrates Stripe for billing. The team wraps it in an anti-corruption layer: nothing in the core domain references a Stripe Customer or PaymentIntent directly; the layer translates those into the product's own Account and Charge concepts. When Stripe rate-limits the integration to 100 requests per second, the back-pressure and retry logic sit in that one layer, contained at a single seam. When Stripe deprecates an API version with a six-month window, one adapter changes. A vendor outage degrades one capability behind a known seam, and the local model keeps its vocabulary intact.

External API vs. its neighbours

• API contract🤝API ContractEngineeringAn API contract or specificationView reference → is the formal specification of an interface (its endpoints, schemas, and guarantees), whether the interface is yours or theirs. An external API is the dependency itself, owned by a third party; its contract is something you read and adapt to, not something you author.
• Integration pattern🔗Integration PatternEngineeringAn integration pattern (saga, event sourcing, etc.)View reference → is the style of connection (messaging✉️MessagingGo-To-MarketMessaging framework and key messagesView reference →, RPC, file transfer, shared database). An external API is one concrete thing you connect to; the pattern describes how you reach it and others like it.
• Integration partner🗿Integration PartnerPartners & EcosystemAn integration partnerView reference → is the organisation behind the interface, the commercial and contractual relationship. An external API is the technical surface that partner exposes; one partner may expose several APIs, and vendor risk🎲RiskComplianceA risk to the product or businessView reference → lives at the partner level even when the failure shows up at the API.

In the graph

In the Unified Product Graph, external_api🌐External APIEngineeringAn external API consumed by the product is a leaf in the Engineering & Platform region, reached by three hierarchy and cross-domain edges that capture who depends on it and why. product_connects_to_external_apiProductconnects toExternal APIhierarchy records the product-level dependency; bounded_context_connects_to_external_apiBounded Contextconnects toExternal APIhierarchy localises it to the part of the system that owns the integration, which is where Evans' anti-corruption layer belongs; and integration_partner_connects_external_apiIntegration PartnerconnectsExternal APIcross-domain reaches across into the partner that supplies it. Modelling all three lets a single query answer the question vendor risk always raises: if this dependency breaks or changes its terms, which contexts, which products, and which commercial relationship are exposed.