Software

API Development

Interfaces other people can build against without asking you questions

How this is usually engaged

Scope depends on whether the API serves your own applications, named partners, or an open developer audience — the technical work is similar but the documentation, support and versioning obligations differ substantially. We agree that audience before estimating, because it is the main driver of cost.

Start a project brief

Practice: Software Engineering
Sectors: 4 served
Process: 5 stages
Standard: Built and tested to WCAG 2.2 AA

Designing, building and versioning APIs — for your own applications, for partners, or as a product — with documentation, authentication and a versioning policy decided before the first consumer arrives.

01What this solves

The problem this addresses

An API is a promise about behaviour that other people build on, which makes it much harder to change than the code behind it. Most of the pain comes from decisions deferred: no versioning policy, so the first breaking change breaks a partner; error responses invented per endpoint, so consumers cannot handle failure generically; documentation written once and now wrong; and no rate limiting, so one badly written client can degrade the service for everyone.

02Capabilities

What is included

Contract-first design

An OpenAPI or GraphQL schema agreed before implementation, reviewed with the teams who will consume it while changes are still free.

Authentication and authorisation

Token issuance with scopes, expiry and per-consumer revocation, plus the machine-to-machine flows partner integrations need.

Versioning and deprecation

A stated policy for what constitutes a breaking change, how versions run in parallel, and how much notice consumers get before one is retired.

Rate limiting and quotas

Limits per credential with clear headers and error responses, so a consumer can back off correctly instead of retrying into a wall.

Generated documentation

Reference documentation produced from the specification, with worked examples and a sandbox environment consumers can call before signing anything.

Contract testing and monitoring

Automated tests against the specification in the pipeline, and production monitoring of latency and error rates broken down per consumer.

03Use cases

Where this work usually starts

Opening data to partners

Distributors, brokers or resellers currently receiving spreadsheets by email who could pull current data themselves.

Logistics & Transport

A shared interface for your own applications

Web, mobile and internal tools each querying the database differently, so business rules are implemented three times and agree twice.

Replacing an API you cannot change

An interface with active consumers, no versioning policy and no specification, where every improvement risks breaking someone.

Finance

04Approach

How we approach it

We design the contract before the implementation, working from what consumers need to accomplish rather than from the shape of your database tables. The specification is written first and generates the documentation, so the two cannot drift apart. Authentication, pagination, filtering, error format and versioning are decided once and applied consistently across every endpoint, and we test against the specification so a change that breaks the contract fails the build rather than a partner's integration.

05Process

How the work runs

The order matters more than the ceremony. Stages overlap in practice, but none of them is skipped.

01
Consumer research
What each consumer is trying to accomplish, and how many calls their task should take.
02
Contract design
Resources, operations, error format and pagination agreed in specification form before code exists.
03
Reference implementation
A first slice built and called by a real consumer, which is where contract problems actually surface.
04
Harden
Authentication, rate limits, validation, monitoring and the sandbox environment.
05
Publish and support
Documentation released, consumers onboarded, and usage watched to find the endpoints people struggle with.

06Deliverables

What you receive

Everything below is handed over as part of the engagement. If you take the work elsewhere afterwards, the next team has what it needs.

API specificationOpenAPI or GraphQL schema as the agreed source of truth.
Implementation with authentication, rate limiting and error handling
Generated reference documentation and worked examples
Sandbox environment with representative test data
Versioning and deprecation policy
Contract test suite and per-consumer monitoring

07Technologies

What we use on this work

These entries are drawn from our managed technology directory, which records why each one is in our stack and what we reach for it for. Nothing outside this list is claimed for this service.

Languages & Runtimes

TypeScript
Node.js
Go

Data & Storage

PostgreSQL
Redis

DevOps & Operations

Docker
Kubernetes
Sentry

The full technology directory

Highlighted entries are used routinely on delivery work

08Security

How this is kept secure

Authentication uses tokens with defined scopes and expiry, issued per consumer so access can be revoked individually without affecting others. Authorisation is checked per request against the caller's scope and their relationship to the resource, never inferred from a prior call. Rate limits are applied per credential, request payloads are validated against the schema before processing, and responses are filtered so a change to an internal model cannot accidentally expose new fields.

Our full security and quality approach

09Questions

Asked before we start

REST or GraphQL?

REST is the right default for partner and public APIs: it is cacheable, widely understood, and easier for a consumer to integrate with basic tooling. GraphQL earns its added operational complexity when varied clients need different shapes of the same data and over-fetching is a genuine cost. We ask who is calling it and from what before recommending either.

Do you provide the SDKs for our API?

We can generate clients from the specification for common languages, which is enough for most partner integrations. Hand-written, idiomatic SDKs with their own release cycle are a separate ongoing commitment, and unless your API is the product itself, they are usually not worth the maintenance. Good documentation and a sandbox solve more integration problems than an SDK does.

How do you handle breaking changes?

The versioning policy is agreed before launch, because retrofitting one to an API with live consumers is the expensive path. Typically the current and previous versions run in parallel for a stated notice period, with deprecation signalled in response headers and consumer usage monitored so you know who has not migrated. Additive changes are not breaking, and we define that in writing.

Can you expose our legacy system through a modern API?

Often yes, with an API layer in front that translates and enforces a clean contract. Be aware of what this does and does not fix: it improves the interface for consumers but inherits the legacy system's performance, availability and data quality. If the underlying system is the actual constraint, a facade will disguise that rather than solve it.

START HERE

Talk to us about API Development

The project brief takes about five minutes and gives us enough to have a useful first conversation about API Development rather than a generic one. If you would rather just ask a question, the short form is there for that.

Start a project Send a short message

We read every enquiry ourselves. If we are not the right fit, we will say so and tell you what to look for instead.