REST APIs
Resource-oriented services with consistent conventions, pagination, filtering and predictable status codes.
Once something external consumes your API, you cannot change it unilaterally. That is the whole discipline: designing an interface you can live with, versioning it so you can evolve it, and documenting it so consumers do not have to guess.
Fig. 01Request and responseIllustrative
Typical stack
Internal APIs forgive breaking changes because you can update both sides at once. Public and partner APIs do not. We design as though the consumer is external even when it is not, because internal consumers have a habit of becoming external ones.
Specification first. An OpenAPI or GraphQL schema agreed before implementation, so consumers can start work in parallel.
Versioning strategy. Decided up front, with a deprecation policy, rather than improvised at the first breaking change.
Contract tests. The specification is executable. Drift between documentation and behaviour fails the build.
Errors as part of the design. Consistent, machine-readable error responses, not whatever the framework happened to emit.
Resource-oriented services with consistent conventions, pagination, filtering and predictable status codes.
Schema-first services with depth and complexity limits, so a single query cannot take down the backend.
OAuth 2.0, API keys, scoped tokens and per-consumer permissions enforced at the gateway and again in the service.
Per-consumer limits with clear headers and predictable behaviour under pressure, rather than silent failure.
Reference documentation produced from the specification, so it cannot drift from the implementation.
Outbound event delivery with signing, retries and a redelivery mechanism consumers can trigger themselves.
The specification is the deliverable that matters first. Everything downstream — mocks, client SDKs, tests, documentation — is generated from it.
Every engagement ends with artefacts you own outright and can hand to another team without calling us first.
A machine-readable specification. OpenAPI or GraphQL SDL, versioned in your repository as the source of truth.
The service implementation. With authentication, rate limiting and structured logging already wired in.
Published reference documentation. Generated from the specification, with worked examples for the common calls.
A contract test suite. Running in CI, so a breaking change is caught before a consumer finds it.
REST for straightforward resource access and for partners who want something conventional. GraphQL when consumers genuinely need to shape their own queries across a connected graph. Choosing GraphQL for a handful of endpoints adds cost without return.
Usually a major version in the URL path, with additive-only changes within a version, plus a written deprecation window. The important part is that the policy exists before the first consumer arrives.
Yes — that is a common brief. The API becomes the stable contract while the system behind it is modernised or replaced, without consumers having to care.
We can generate them from the specification for the languages your consumers use. Hand-written SDKs are a maintenance burden we would rather not create.
Partners, a mobile app, another internal team. Tell us who the consumer is and we will design an interface that does not need breaking next year.