Your frontend asks your backend for data, and the backend answers. The exact shape of that exchange, what you send and what comes back, is a promise both sides rely on. Change it carelessly and every screen that read the old shape breaks at once. This chapter gets you a contract that stays stable as the app grows.
4.5.1Design the contract first
Your API is the set of addresses your app exposes for others to call. Each one is an endpoint: a single URL plus a method (GET /posts, POST /posts) that does one job. The contract is the agreed shape of every request and response those endpoints exchange.
Decide that shape before the agent writes a single handler. When the request and response are pinned down first, the frontend and backend can be built in parallel against the same agreement instead of guessing at each other.
4.5.2Consistent shapes and errors
Wrap every response in one consistent envelope, the same outer shape whether the call succeeds or fails. Success flag, the data, the error, and a meta block for pagination:
{
"success": true,
"data": { "id": 42, "title": "First post" },
"error": null,
"meta": { "page": 1, "perPage": 20, "total": 137 }
}
A failure reuses the same envelope, flips the flag, and fills error instead of data:
{
"success": false,
"data": null,
"error": { "code": "not_found", "message": "No post with id 42" }
}
Give each error a stable code your frontend can branch on, a human message, and a real HTTP status (MDN lists them): 200 for success, 404 for not found, 422 for bad input.
4.5.3Versioning without breaking clients
Put a version in the path from day one (/v1/posts). Adding a new optional field is safe: old clients ignore it, so it stays in v1. Removing or renaming a field breaks anyone reading the old shape, so that goes in a new /v2 while v1 keeps running.
This is exactly the split semantic versioning formalizes: additive is a minor change, breaking is a major one. You do not cut clients off, you give them a version to move to on their own schedule.
This prompt hands the whole contract to your agent:
Act as a senior engineer designing my API contract.
Define one consistent response envelope for every
endpoint: a success flag, a data field, an error
object, and a meta block for pagination. Give me the
exact JSON for a success and an error response, a small
set of stable error codes, and the HTTP status each
maps to. Then propose a versioning scheme (path or
header) and the rule for what counts as a breaking
change versus a safe additive one, so existing clients
never break.
My API and what it returns:
Do this now: paste the prompt with your endpoints, let your agent define the envelope, error codes, and versioning rule, then hold every new endpoint to that one shape.
