api-contract-review

API contract review

A contract is the part you can't take back. Review it before it merges, not after someone depends on it.

What counts as a contract

HTTP routes, plugin setup/start return values, exported package symbols, saved object schemas and their migrations, persisted config, URL and locator state, and any type another team imports.

Checklist

Breaking change analysis

Walk each change and classify it:

• Safe: adding an optional field, adding a new route, widening an accepted input, narrowing a returned union to fewer cases only if no consumer switches on the removed case.
• Breaking: removing or renaming a field, making an optional field required, narrowing accepted input, widening a returned union, changing a status code, changing a default that alters behaviour.

For each breaking change, find the consumers. Grep for the symbol, the route path, the saved object type. Report the call sites you found and say plainly if you could not establish the full set.

Input validation

Every request input needs a schema, and every string, array, and object needs a bound. Unbounded input is a denial-of-service vector.

schema.string({ maxLength: 1_000 })
schema.arrayOf(itemSchema, { maxSize: 100 })
z.string().max(1_000)
z.array(item).max(100)

Flag: unbounded schema.string() / z.string(), unbounded arrays, schema.any(), recursive schemas without a depth limit, and numbers without a range where a range is meaningful.

Also check: is validation at the boundary, or does raw input reach a query builder? Are ids validated before interpolation?

Response shape

• Is the success shape stable, or does it leak internal structure that will change?
• Are errors typed and consistent? A route that returns a bare string on one path and a Boom object on another has no contract.
• Does it expose data the caller shouldn't see? Internal ids, stack traces, other tenants' fields.
• Partial success: if the operation can half-fail, does the response say which parts failed? Prefer a partialFailures array over throwing on the first error.