API Design Best Practices: Rules for Contracts That Don't Break

What Public API Design Actually Protects

Ask five engineers why an API broke a client and four will describe a caller who depended on something that was never part of the documented contract - a field, an error message, a status code that just happened to be there. That's usually not caller error. Anything a client can observe eventually gets depended on, whether it was documented or not, which is why "we never promised that" stops working as a defense the moment someone's production system is reading it.

None of the seven principles below are really about sloppy engineers. They're about the fact that the correct move from inside one service - ship the field, return the object you already have - is different from the correct move for every client who will ever call you, and that gap is invisible from a seat that only has visibility into one service.

1. A Version Number Is Your Escape Hatch

A mobile team ships a boolean field called isVerified. Eighteen months later, verification needs three states instead of two, but four client teams and two partner integrations have already written conditionals against a boolean, and there's no version to change into - only the wall of every consumer's existing code. Every public route carries an explicit version, in the path or a required header, and no field or behavior in a published version is ever removed, renamed, or reinterpreted.

app.get('/accounts/:id', getAccount);
// no version segment — this handler
// now owns every future contract change

app.get('/v1/accounts/:id', getAccountV1);
app.get('/v2/accounts/:id', getAccountV2);
// v1 untouched — added alongside, not edited

The honest tradeoff: running two or three live versions in parallel means doubled test surfaces and a deprecation clock someone has to actually watch. Stripe has kept every version of its API compatible since 2011 by treating each one as a permanent branch of behavior, and even they save a breaking major version for the rare case that's worth the cost.

2. Your Response Type Defines What's Observable

A /employees/:id endpoint returns whatever the ORM's default serializer produces, including a salary_band column and a password_reset_token added for an unrelated internal tool three sprints ago. Nobody decided to expose those fields - the serializer did, the moment the columns existed. Every endpoint returns a value bound to a declared response type, built by explicit field assignment, never a persistence entity and never a reflective serialization.

app.get('/v1/employees/:id', async (req, res) => {
  const employee = await db.employees.findById(
    req.params.id
  );
  res.json(employee);
});

interface EmployeeResponse {
  id: string; name: string;
  department: string; startDate: string;
}
app.get('/v1/employees/:id', async (req, res) => {
  const e = await db.employees.findById(req.params.id);
  res.json({
    id: e.id, name: e.full_name,
    department: e.dept,
    startDate: e.start_date.toISOString(),
  });
});

Timestamps get the same explicit treatment for the same reason: a format with no stated UTC offset gets reinterpreted in whatever zone the reader happens to be in, which is exactly the failure mode RFC 3339 exists to close off.

3. No Request Writes Straight to Storage

A profile-edit endpoint accepts the request body and passes it straight into an update call. Someone adds "role": "admin" to a routine display-name change, and if nothing strips it, the role updates along with the name, because the update call has no idea which fields were ever supposed to be writable from outside. Every request deserializes into a dedicated request type, validated against a declared schema before any handler logic runs.

const updateSchema = z.object({
  displayName: z.string().min(1).max(80)
});
app.patch('/v1/users/:id', async (req, res) => {
  const patch = updateSchema.parse(req.body);
  // throws before persistence is touched
  await db.users.update(req.params.id, {
    display_name: patch.displayName
  });
  res.status(204).send();
});

This is what OWASP now folds into Broken Object Property Level Authorization: excessive exposure and mass assignment turned out to share one root cause — an API that doesn't control which object properties a caller can read or write — which is why the 2023 list merged them into a single category.

Validating before persistence means every write path carries a small tax - one schema per operation instead of one entity for everything. The alternative is betting that no caller ever sends a field they shouldn't, which is a bet with a documented loss history.

4. HTTP Methods and Status Codes Are Promises Too

A cost-saving change adds a GET endpoint that triggers a background export job and decrements a monthly quota as a side effect. A link-preview crawler visits it once. A corporate proxy prefetches it. By the time anyone notices, quota has been consumed by requests no actual user intended to send. Mutating endpoints use POST, PUT, PATCH, or DELETE - never a state change inside a GET or HEAD handler - and status codes match the outcome of the operation.

// wrong: GET /v1/subscriptions/:id/cancel
// mutates state through a "safe" method
app.post(
  '/v1/subscriptions/:id/cancellation',
  cancelSubscription
);

Safe methods are ones where the client does not request, and does not expect, any state change on the server — incidental side effects like logging aside. That's the definition RFC 9110 anchors, and it's also where status code meaning lives, which is why returning 200 on a failed operation quietly breaks every cache, proxy, and retry mechanism reading the status line instead of the body.

Moving a mutation off GET sometimes means breaking an integration that was quietly relying on the shortcut - which is exactly the cost of fixing something that should never have been observable in the first place.

5. Failures Need One Shape and No Stack Trace

A 500 handler returns the raw exception message because it was fast to write, and nobody circled back. Six months later that message includes a table name, a column name, and the exact SQL that failed, delivered straight to whatever client triggered the bug. Every error response, from every endpoint, comes back in one declared shape - a stable code, a human-readable message, and field-level detail where relevant - never an exception message or stack trace.

app.use((err, req, res, next) => {
  res.status(500).json({
    error: err.message,
    stack: err.stack,
  });
});

app.use((err, req, res, next) => {
  logger.error({ correlationId: req.id, err });
  res.status(500).json({
    type: '.../problems/internal-error',
    title: 'Something went wrong',
    correlationId: req.id,
  });
});

Diagnostic worth running: pull ten error responses from ten different endpoints in this API. If they don't share the same field names, there's no error shape here - just ad hoc guesses that happen to return JSON.

6. Unbounded Endpoints Become Unbounded Liabilities

A list endpoint returns every order on an account, no limit. It works fine in the demo with twelve orders. Eighteen months later a large customer has 400,000, the endpoint times out, and the fix isn't just adding a page parameter - now every client that assumed it always got everything back in one call has to change too. List endpoints return bounded, cursor-paginated pages, and every public endpoint carries a rate limit keyed to the authenticated principal or API key.

Diagnostic worth running: if a list endpoint's response time scales with total row count rather than page size, it doesn't have pagination - it has a ticking clock. If a single API key can exhaust the service's capacity today by sending requests as fast as the network allows, the rate limit doesn't exist yet regardless of what the docs claim.

Google's AIP-158 pagination standard requires a next-page-token field that's only ever absent once the collection is actually exhausted. The rate-limit half sits inside what OWASP now calls Unrestricted Resource Consumption — real cost that partners need documented clearly enough to design around.

7. A Spec Nobody Verifies Is Not a Contract

Team A's OpenAPI file describes eleven endpoints. The service actually exposes fourteen — three routes were added directly in code during an incident and nobody circled back to the spec, because it was never checked against reality, only written once and trusted forever after. A machine-readable specification lives in the repository, generated from or validated against the implemented handlers, and no endpoint gets published that's absent from it.

Rule of thumb: pick any route at random and ask if it's in the spec file. Pick any path in the spec and ask if a handler actually implements it as described. If either question makes someone go check, the spec isn't a contract - it's a rumor with a nice YAML format.

Here's the problem with the six principles above: each one is something an individual team can get exactly right in the one service it owns, and still, once an org has forty services owned by a dozen teams, whether the aggregate is actually true isn't something any one person can verify by reading through a quarter's worth of pull requests. That's a different kind of problem than any of the other six.

How Pandorian Enforces This Guide

Every principle above is something one engineer can get right in one service and still not have true anywhere else in the org, because the drift is invisible from inside any single pull request - it only shows up in the aggregate. Pandorian enforces this guide across three surfaces:

Caught at PR level

A new handler that binds a request payload directly onto a persistence entity, a new GET route that performs a write, or a response built by reflecting an object instead of mapping a declared type surfaces with the specific line, the rule, and a suggested fix.

Full scans

An on-demand scan across the whole codebase establishes the day-one baseline: every currently unversioned public route, every list endpoint still returning an unbounded collection, every error response still leaking exception detail.

Scheduled scans

The same scan, run on a cadence, catches drift introduced outside any pull request - a rate limit quietly dropped by a gateway config change, or a published field silently renamed by a migration that never touched the route serializing it.

A Taste of the Guideline Package

Four of the checks that ship in this package - each runs at the PR level, on full or scheduled scans, or several at once.

FAQ