APIs & Integrations

Integration work is rarely difficult because of the API call. It is difficult because of what happens when the call times out after the remote system already committed, or the webhook arrives twice, or a partner changes a field without telling anyone. The engineering that matters is all in the failure cases.

Designing an API others have to live with

If you are publishing the API, the decisions are about the people integrating against it: consistent resource naming and response shapes, pagination that works on large result sets rather than offset queries that degrade, filtering and sorting that cover real needs, errors that say what went wrong and what to do, and rate limits communicated in headers rather than discovered by being blocked.

Versioning from day one, because you will need to make a breaking change and doing so without a version means breaking every consumer simultaneously. And documentation generated from the schema, since hand-written API docs drift within weeks.

REST, JSON:API or GraphQL

Plain REST suits most cases and everybody can consume it. JSON:API adds conventions for relationships, sparse fieldsets and includes, which removes a lot of bikeshedding and is what Drupal ships in core. GraphQL suits clients that need to shape their own queries and benefits front-end teams working against many resources, at the cost of more setup and real care around caching, N+1 queries and query complexity limits.

Any of these is fine. Choosing GraphQL for a two-endpoint integration, or plain REST for a front end that needs twelve round trips per screen, is the mistake worth avoiding.

The failure cases, which are the actual work

• Idempotency. Every write that could be retried needs an idempotency key, so a duplicate request returns the original result rather than creating a second record.
• Asynchronous by default. A synchronous call to a third party puts their uptime in your critical path. Queue the work, respond immediately, process in the background.
• Retries with backoff. Exponential, jittered, and with a limit. Retrying immediately and forever turns a partner's brief outage into your incident.
• Dead letters someone watches. A dead-letter queue nobody monitors is silent data loss with extra steps.
• Reconciliation. Despite all of the above, systems drift. A periodic job comparing both sides and reporting the differences is what turns "we think it works" into knowing.

Webhooks, in both directions

Receiving: verify the signature, respond fast and process asynchronously — providers time out and retry if you take too long doing work inline. Treat delivery as at-least-once and deduplicate on the event identifier, because you will receive duplicates.

Sending: sign your payloads, retry with backoff, expose delivery history so consumers can debug their own endpoint, and let them replay events. Webhook delivery without a replay mechanism generates support tickets you cannot resolve.

Integrating with systems you do not control

Much of this work involves an older internal system, an ERP, or a partner API documented optimistically. The practical approach is an anti-corruption layer: your application talks to a clean internal interface, and one adapter absorbs the remote system's quirks. When the partner changes something — and they will, without notice — the damage is contained to the adapter.

Alongside that: contract tests against a recorded set of real responses, so a change on their side fails in CI rather than in production, and logging of raw payloads for long enough to diagnose what actually arrived.

Data migration and one-off syncs

The same principles apply to migrations between systems: repeatable and re-runnable rather than one-shot, validated against the source, idempotent so a partial failure can be resumed instead of restarted, and reconciled at the end with counts and spot checks rather than declared complete.

Common questions