Writing the API contract: Full-Stack Development (Beginner)

What is an API contract?

An API (Application Programming Interface) is the set of requests a backend accepts. A contract is the written list of those requests, with the exact shape of what goes in and what comes out.

Think of it like this: A restaurant menu card is a contract. The waiter promises to take orders only for dishes on the card, and the kitchen promises it can cook every dish on it. Neither needs to watch the other work. If the kitchen changes a dish without updating the menu, orders go wrong. An API contract keeps the frontend (waiter) and backend (kitchen) in agreement.

Every endpoint has five parts

Method: what kind of action (GET reads, POST creates, PATCH changes part of something, DELETE removes).
Path: the address, such as /api/notes/:id. ":id" is a placeholder for a real number like 7.
Request body: the JSON the client sends (only for POST and PATCH here).
Response: the JSON the server sends back when things go well.
Status codes: the number that says how it went (200 OK, 201 Created, 400 bad input, 401 not logged in, 404 not found).

Method and path	Request body	Success	Errors
GET /api/notes	-	200, { notes: [...] }	401
POST /api/notes	{ title, body, pinned }	201, the new note	400, 401
GET /api/notes/:id	-	200, the note	401, 404
PATCH /api/notes/:id	any of { title, body, pinned }	200, the updated note	400, 401, 404
DELETE /api/notes/:id	-	204, no body	401, 404
POST /api/auth/signup	{ name, email, password }	201, { user }	400, 409 (email taken)
POST /api/auth/login	{ email, password }	200, { user }	400, 401
POST /api/auth/logout	-	204	-

json

// Request: POST /api/notes
{ "title": "Physics formulas", "body": "V = IR", "pinned": true }

// Response: 201 Created
{
  "id": 12,
  "title": "Physics formulas",
  "body": "V = IR",
  "pinned": true,
  "created_at": "2026-02-01 08:00",
  "updated_at": "2026-02-01 08:00"
}

One endpoint written out fully. Note pinned is a real true/false in JSON, even though the database stores 1 or 0.

One shape for every error

Decide one error shape and use it everywhere. Our Notes app always answers errors as { "error": { "code": "...", "message": "..." } }. The code is short and fixed, for programs to check ("VALIDATION_ERROR", "NOT_FOUND"). The message is friendly text a person can read.

json

// Response: 400 Bad Request
{ "error": { "code": "VALIDATION_ERROR", "message": "Title is required" } }

Because every error looks the same, the frontend needs only one piece of code to show errors.

Contract first, then build in parallel

Contract-first means you write and agree on the contract before writing the code. The frontend developer can then build screens against a mock server: a fake backend that returns the example responses from the contract. The backend developer builds the real thing at the same time.

Teams often write contracts in OpenAPI, a standard format (YAML or JSON) that describes every endpoint. Tools read an OpenAPI file to make documentation pages, mock servers and even test checks automatically.

Tip: Keep the contract in your repository next to the code, and update it in the same commit when an endpoint changes. An old contract is worse than none, because people trust it.

Careful: Never change the shape of a response that a live app uses (for example renaming title to name) without telling the other side. The app on users' phones will break at once.

Writing the API contract

Explanation

What is an API contract?

Every endpoint has five parts

One shape for every error

Contract first, then build in parallel

Watch the lesson

In real life: A train booking app and its partner apps

Practice (0/3 done)

Quick quiz

Read more (free)