Pattern Name: API-First Design Category: Application Architecture / Integration Architecture Complexity: Low to Medium Stability: high: de facto standard for modern application and integration design
APIs are the connective tissue of modern digital systems. Applications expose APIs to consumers: whether internal services, mobile clients, partner systems, or AI tools. In traditional development, APIs are designed after the application’s internal logic is built: the API reflects what the implementation happens to produce rather than what consumers actually need. This produces APIs that are inconsistent, poorly documented, hard to version, and difficult to govern at scale.
API-first inverts this: the API contract is defined first, before any implementation begins. The implementation is constrained to honor the contract.
How do you design application and service interfaces that are consistent, stable, well-documented, and suitable for diverse consumers: when development teams are under pressure to deliver implementation quickly and API design is typically treated as an afterthought?
APIs designed as afterthoughts tend to reflect implementation details rather than consumer needs. They are inconsistent across services (different teams use different conventions for the same concepts), hard to evolve without breaking consumers, poorly documented (because documentation is also an afterthought), and resistant to governance. The cumulative effect across a large application portfolio is an integration landscape that is expensive to maintain and difficult to extend.
Define the API contract: the interface specification: before writing a line of implementation code. The contract is the authoritative source of truth for what the API does, what requests it accepts, and what responses it returns. Implementation proves the contract; the contract does not describe the implementation.
API-First in practice:
Contract-first specification: API contracts are defined using a formal specification language. For REST APIs, OpenAPI Specification (OAS, formerly Swagger) is the standard. For event-driven APIs, AsyncAPI. For GraphQL, the schema definition language. These machine-readable specifications drive tooling: mock servers, client SDK generation, test case generation, and documentation.
Design review before implementation: The API contract is reviewed by the API governance team (or architecture team) before implementation begins. Consumers are consulted during design: they provide requirements, they validate the proposed contract, and they are the audience the design must serve. This is analogous to an Architecture Decision Record for the interface: the decision is made explicitly, with rationale, before it is built in.
Mock-first development: Once the contract is approved, mock servers are generated from the specification. Consumer teams can begin integration work against the mock immediately, in parallel with the provider team implementing the real API. This eliminates the blocking dependency that typically delays integration work.
Versioning from day one: Breaking changes to the API contract require a new version. The versioning strategy (URI versioning, header versioning, or semantic versioning) is defined in the API governance standard and applied consistently. Deprecation policies (how long an old version will be supported, how consumers are notified) are defined upfront.
API catalogue and discovery: Published APIs are registered in a central API catalogue: a searchable directory of available APIs with their specifications, documentation, SLAs, and ownership. The catalogue is the mechanism by which teams discover existing APIs before building new ones, and by which governance can see the full API landscape.
OpenAPI and Swagger are often used interchangeably: Swagger refers to the original specification (and the tooling ecosystem around it); OpenAPI is the specification standard maintained by the OpenAPI Initiative from version 3.0 onwards. Both refer to the same YAML/JSON format for describing REST APIs.
Element types to use:
Diagram types: ArchiMate Application Layer diagram showing API consumers and providers; UML Component diagram for detailed interface contract structure; sequence diagrams for API interaction flows; information structure diagrams for the data models
MDG considerations: The «OpenAPI» stereotype with a mandatory specification URL tagged value enforces the discipline that API contracts are documented before implementation. A validation rule preventing publication of Application Interface elements without a spec URL is a lightweight but effective governance mechanism. Build a model search listing all published APIs with their owners, versions, and SLA tags: this is the foundation of an EA-grounded API catalogue.
Package structure: An API Catalogue package containing all published APIs, organized by domain. An API Standards package containing the governance standards, versioning policy, and design guidelines. A Consumer-Provider Mapping package with diagrams showing which applications consume which APIs: critical for impact assessment when APIs are versioned or deprecated.
EA GraphLink and AI integration: The API catalogue is one of the most immediate beneficiaries of AI integration. With EA GraphLink connected, developers and architects can ask: “What APIs does the Customer domain publish?”, “Is there an existing API for retrieving account balance, or do we need to build one?”, “Which applications consume the v1 Payments API, and will they be affected by the planned v2 migration?”. These are questions that developers ask every day. Today, they either dig through documentation, ask a colleague, or build a duplicate. With AI-assisted access to the EA model via Kernaro or Copilot, developers get accurate answers from the authoritative source instantly. This is one of the most direct demonstrations of EA value to a software delivery organization.
Talk to a Sparx Services architect about where your organization is on the journey and what the next stage looks like.