REST API development

Design decisions that matter

Following HTTP semantics

Clients and tools assume HTTP methods behave as RFC 9110 defines them. GET should only read; PUT and DELETE should be idempotent, meaning repeating the same request has the same effect as sending it once; POST is not idempotent, so repeating it may create another record. Respecting these rules lets clients retry safely after network failures. For operations created with POST, such as payments or orders, offering an idempotency key lets clients retry without creating duplicates.

Unexpected behaviour, such as a GET that changes data, causes subtle bugs for every consumer.

Errors consumers can act on

Design and document first

Describing the API before building it, in a format such as the OpenAPI Specification, which defines a standard, language-agnostic way to describe HTTP APIs, lets future consumers review it early, generates documentation and test tools, and gives developers a contract to build against. Changes at the design stage cost little; changes after partners have built on the API are disruptive. Involve at least one real consumer, such as your mobile developers or a key partner, in reviewing the draft.

Keep the description updated as the API evolves, so documentation never drifts from reality.

Paging large lists

Endpoints that return lists should return them in pages, with a clear way to fetch the next page and sensible maximum page sizes. Cursor-based pagination copes better than page numbers when records are added during paging. Offering filters such as 'changed since' lets consumers sync efficiently instead of rereading everything, which also reduces load on your systems.

Versioning without breaking people

Additive changes, such as new optional fields, rarely break consumers. Removing fields, renaming them or changing behaviour does. Release breaking changes as a new version, run old and new side by side for a published period and tell consumers well in advance. A clear deprecation policy is a promise that lets others depend on your API with confidence.

Security from the start

Authentication, authorisation on every object, rate limits and input validation must be designed in. The REST API development services page covers security testing against the OWASP API Security Top 10.

Designing for your consumers

Different consumers need different things. Your own mobile app wants compact responses tuned to its screens; a partner's system wants complete records and reliable change feeds; a customer's developer wants clear examples and a sandbox. Talk to representative consumers about the tasks they will perform, and design endpoints around those tasks rather than mirroring your internal database tables. An API that exposes internal structure directly is hard to change later and confusing to use.

Consistent naming across endpoints makes the whole API easier to learn.

Performance and limits

Set rate limits to protect your systems and return 429 responses with guidance when they are exceeded. Keep responses reasonably sized, support filtering so consumers request only what they need, and monitor slow endpoints. Publishing your limits lets consumers design their integrations to stay within them.