← Engineering · Case studies API economy · Case study

Domain-driven, contract-first API

A domain model, ubiquitous language, and OpenAPI 3 specification define one API, one bounded context, and one datastore — designed and agreed before any code is written.

Overview

APIs were being shaped by database tables and org charts rather than the business, with inconsistent terminology and shared datastores creating hidden coupling. The aim was an API that models a real service boundary — designed contract-first, before implementation.

The logical boundary is defined as one API with a specification, a domain model that accurately models the bounded context, and a primary datastore the API owns — with all access to that datastore going through the API.

The challenge

APIs shaped by database schemas and team structure, not the business domain
Inconsistent terminology between the model, the code, and the documentation
Shared datastores created hidden coupling between services
Specifications were written after the code, so consumers waited

Our approach

Modelled the bounded context with domain-driven design — business entities, behaviours, and relationships
Captured the ubiquitous language so the team and the specification share one vocabulary
Authored the OpenAPI 3 specification as the contract, closely aligned to the domain model
Produced C4 context and container diagrams to communicate the architecture and foster review
Enforced one API → one bounded context → one primary datastore, with all persistence accessed through the API

Results & business impact

The API reflects a real business boundary rather than a database schema
One vocabulary spans the domain model, the specification, and the docs
The datastore is owned by a single service, removing hidden coupling
The contract is agreed before code, so consumers build in parallel

Tools & technology

Domain-Driven Design OpenAPI 3 Ubiquitous language C4 model Bounded context Service boundary Semantic versioning