Backend & API Development

The API contract comes before the code

A backend is a promise made to other software — your mobile app, your web front-end, a partner's system. If that promise is not written down, the mobile team guesses, the web team guesses differently, and integration week becomes a negotiation.

So we produce an OpenAPI specification before implementation: every endpoint, its parameters, its response shape, its error responses, and its authentication requirement. It takes a couple of days and it unblocks everything — the mobile team can build against a mock server while the backend is still being written, instead of waiting. It also becomes the artefact you hand to a partner or a future developer, which is worth more than any amount of prose documentation.

Versioning, because installed clients never all update

Once a mobile app is on real phones, some users will run a build from a year ago indefinitely. Any change to a response shape that the old app depends on breaks it, and you cannot recall the installs.

So endpoints are versioned from the first release — /v1/orders — and inside a version we only make additive changes: new optional fields, new endpoints. Removing a field, renaming one, or changing a type is a new version. We also build a minimum-supported-version check so a dangerously old client can be told, politely, to update. None of this is expensive up front and all of it is painful to retrofit.

Authentication: what we actually use and why

For a mobile app or a separate front-end, we use short-lived access tokens paired with longer-lived refresh tokens, with the refresh token revocable server-side. The reasoning is practical rather than fashionable: a stateless token that lives for thirty days cannot be invalidated when a phone is lost or an employee leaves, and "log out everywhere" is a feature clients always eventually want.

The details that matter more than the token format: tokens stored in the platform's secure storage rather than plain preferences; password hashing with a modern algorithm and never a fast hash; rate limiting and lockout on login and password-reset endpoints, because credential-stuffing is automated and constant; password reset tokens that are single-use and short-lived; and permission checks enforced server-side on every request. Hiding a button in the interface is not authorisation — if the endpoint does not check, the endpoint is open.

Idempotency, for anything that costs money

Networks fail after the server has already done the work. A client that retries a payment, an order or a transfer must not cause it to happen twice.

Our pattern is a client-supplied idempotency key on every state-changing endpoint where duplication would be harmful. The server records the key with the result; a repeat request with the same key returns the original response rather than performing the action again. It is a small amount of code and it prevents the single worst class of bug in transactional systems.

Lists: pagination, filtering, and the N+1 trap

Endpoints that return collections cause most real-world performance problems. Three rules we hold to:

• Never return an unbounded list. Every collection endpoint paginates, with a maximum page size the server enforces regardless of what the client asks for. Cursor-based pagination for anything that changes while being read, since offset pagination silently skips and repeats rows.
• Filter and sort on the server, on indexed columns, with the allowed fields whitelisted. Accepting arbitrary sort fields from a client is both a performance and a security problem.
• Eliminate N+1 queries. A list endpoint that runs one extra query per row is the most common cause of a slow API. We check query counts as part of review, not after a complaint.

Alongside that: indexes designed against the queries you will actually run, and a hard rule that reports never run against the live transactional tables at peak time if they can be cached or moved to a read replica.

Anything slow goes into a queue

Generating a PDF, sending a hundred emails, processing an upload, calling a slow third-party API — none of that belongs inside a request the user is waiting on. We move it to a background queue with retries, exponential backoff and a dead-letter destination for jobs that keep failing, so failures are visible instead of silent.

The same applies in reverse for webhooks you receive: accept, verify the signature, store the payload, return 200 immediately, and process asynchronously. A webhook handler that does its work inline will eventually time out and cause the sender to retry, and duplicate processing is how you double-charge someone.

Observability, or you are debugging blind

Every backend we ship has structured logging with a request ID that flows through to any downstream call, so a single user's failed request can be traced end to end. Errors go to a tracking service with a stack trace and context rather than into a log file nobody reads. We expose a health endpoint that actually checks dependencies — database, cache, queue — rather than returning 200 unconditionally, and we alert on error rate and response time rather than only on the server being down. A server that is up and returning 500s to everyone is the failure mode simple uptime monitoring misses.

Security basics, done every time

Validate and whitelist every input rather than blacklisting bad ones. Parameterised queries only. Rate limits per endpoint and per account. Secrets in environment variables or a secret manager, never in the repository — and rotated if they ever were. Restrictive CORS rather than a wildcard. No sensitive data in URLs, since URLs end up in logs and analytics. Uploaded files validated by content rather than by extension, stored outside the web root, and served through a controlled path. Dependency vulnerability scanning in the pipeline so you learn about a known issue from your build rather than from an incident.

For choosing the stack itself, our Laravel vs Node.js decision framework covers the trade-offs that actually decide projects, and hosting tiers covers where to run it.