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⛓️DependencyTeam & OrganisationA cross-team or system dependencyView reference → touches only the layer, never the core.

The architectural conditions that make this discipline necessary were set out earlier, in Roy Fielding's 2000 dissertation. Fielding defined REST as a set of six constraints🔒ConstraintStrategyA limit, requirement, or ceiling the product must respect, whether a self-imposed principle or an externally imposed boundaryView reference → on networked systems — among them statelessness, a uniform interface, and a layered architecture — and showed that a uniform interface decouples clients from server internals, while the layered constraint means a consumer cannot assume direct connectivity to the origin. Both properties are load-bearing: a well-designed external API honours them so that its consumers can reason about what they depend on; a poorly designed one collapses them, making every implementation detail a de facto contract.

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.

Richardson and Amundsen's *RESTful Web APIs* (2013) discusses why most APIs reach what Richardson's maturity model calls level 2 — resources plus HTTP verbs — but stop short of level 3, which adds hypermedia controls (HATEOAS) so that clients discover valid transitions from the response itself rather than from documentation. Without that, URL structures and response shapes become hard-coded into client assumptions🤔AssumptionStrategyA belief taken as true that underpins a strategyView reference →, which is why a server-side restructuring that the provider considers internal becomes a breaking change for every consumer.

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📋SpecificationFoundationsA canonical open standard or specification that primitives and products conform toView reference → 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.