API contracts: what the backend owns, what the front end owns, and the schema in the middle

Most friction between a front end and a backend is contract friction. A key that is sometimes missing. A number that arrives as a string on Tuesdays. An enum that grew a value nobody announced. A 200 OK carrying an error body. Each one turns into defensive code somewhere, and that code never gets deleted. This post is about who owns which part of the contract, and how to keep both sides honest with one schema.

Data cleaning is the backend's job#

"Clean" data means it is already in the shape and the canonical format a consumer should get: trimmed and normalised strings, coerced types, dates as ISO 8601 with a timezone, money as integer minor units or a decimal string, enums as stable codes, booleans as booleans, soft-deleted and unauthorised rows filtered out, business rules applied. The backend does this because:

• It is closest to the source of truth and has the full picture: other tables, permissions, the business rules.
• It is one place. Cleaning in each client means web, mobile and partner integrations each drift their own way.
• It is the security boundary. The client's copy of the rules is a suggestion.
• A client that has to "fix up" a response is doing work it should never have been handed, and doing it inconsistently.

If a field can be null, that is a decision the backend made, not an accident the front end inherits.

The cardinal sin: omitting keys#

The single most expensive contract habit is returning { name: "Ada" } sometimes and { name: "Ada", nickname: "Countess" } other times. Now every consumer writes data.nickname ?? fallback everywhere, the type becomes nickname?: string, and optional chaining spreads through the codebase like mould.

// BAD: shape depends on whether a relation was loaded
{ "id": "42", "name": "Ada" }
{ "id": "43", "name": "Grace", "team": { "id": "9", "name": "Compilers" } }

// GOOD: every field always present, explicit empty when there is no value
{ "id": "42", "name": "Ada",   "team": null }
{ "id": "43", "name": "Grace", "team": { "id": "9", "name": "Compilers" } }

• Every field in the contract is always present. If there is no value, send an explicit typed empty: null for "no value", [] for "no items", "" only when an empty string is meaningful.
• null means "known to be absent". A missing key means "someone forgot". JSON has no undefined. A well-typed response never omits.
• Optionality is a modelled decision, and it should be rare. A field that is optional because "the ORM did not load that relation" is a bug in the endpoint, not an optional field.
• Nullable everything is almost as bad. If email is typed string | null but this endpoint's users always have one, the type is lying, and the front end writes a guard that never runs. Model what the endpoint actually guarantees.

Consistency across endpoints#

What the front end owns#

Not data cleaning. The front end should not be trimming strings, coercing types, deduping rows, or applying a business rule the backend skipped. What it does own:

• View models. Mapping the API shape to what a component needs. This is presentation shaping, not repair: formatting a date for display, computing a derived label, grouping rows for a UI. It is the anti-corruption layer from the architecture post.
• Presentation formatting. Locale, currency display, relative time, truncation, pluralisation.
• Interaction and UI state. Loading, empty and error UI, optimistic updates, focus, transitions.
• Input validation for UX. Immediate feedback as the user types. This duplicates server validation on purpose and never replaces it.
• Honouring the states the contract allows. If avatarUrl is nullable per the contract, render a fallback. That is not fixing data, it is holding up your end of the contract.

One schema, guarded on both sides#

The runtime check and the compile-time type must come from a single definition, or they drift. Hand-write a TS type and a separate Zod schema and within a month they disagree.

// contracts/user.ts  (a package both apps import)
import { z } from "zod"

export const Team = z.object({
  id: z.string(),
  name: z.string(),
})

export const User = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(["owner", "admin", "member"]).catch("member"), // survive unknown
  team: Team.nullable(),        // present and null, never omitted
  createdAt: z.string().datetime(),
})

export type User = z.infer<typeof User>          // the type IS the schema
export const UserListResponse = z.object({
  items: z.array(User),
  nextCursor: z.string().nullable(),
})

Backend: validate your own response

Run the schema over the response before it leaves the server, at least in CI and staging, ideally always. Catching a contract violation in your own pipeline costs nothing. The front end catching it in production costs a support ticket and an incident.

// serializer / middleware on the way out
const body = UserListResponse.parse(payload) // throws if the endpoint lies
res.json(body)

Front end: parse once at the boundary

// features/users/api.ts : the only place this endpoint is decoded
import { UserListResponse } from "@acme/contracts/user"

export async function getUsers(cursor?: string) {
  const res = await http.get("/users", { params: { cursor } })
  const parsed = UserListResponse.safeParse(res.data)
  if (!parsed.success) {
    reportContractError("/users", parsed.error, res.data) // loud, with payload
    throw new ApiContractError("/users")
  }
  return parsed.data // components downstream get a guaranteed shape
}

One parse, at the data-access layer, per endpoint. Components never see an unvalidated response, so they never need a guard. No data?.user?.profile?.name ?? "Unknown" five levels deep.

Where each validation lives#

The checklist#

1. Every field always present. null for absent, never omit a key.
2. Optionality is a modelled decision, and it is rare.
3. IDs are strings. One date format (ISO 8601 with timezone). Money as integer minor units or a decimal string.
4. Enums are stable codes, and the client tolerates an unknown value.
5. One casing convention, one error envelope, one pagination shape.
6. One schema definition is the source of the type and the runtime check.
7. The backend validates its own responses in CI.
8. The front end parses once at the data-access layer and fails loud, with no scattered guards.
9. The backend cleans. The front end formats.

Anti-patterns#

• "The front end can just handle it" for a missing or dirty field.
• Making every field nullable so the backend never has to decide.
• Hand-maintained types living apart from the runtime schema.
• Casting the API response to a type with no runtime check.
• Deep optional chaining with fallbacks because the shape is unpredictable.
• A different shape per endpoint for the same entity.
• A 200 OK with an error body.
• Numeric IDs.
• Business logic in the client because the endpoint returns raw rows.