A JSON API over your own kitchen.

Ids are opaque

Never database numbers. They are the same ids the app uses in its own URLs, so an id from a share link works here. Treat them as strings and do not try to order or arithmetic them.

Everything is wrapped in data

A single object comes back under a `data` key, not at the top level. So does a listing, alongside `links` and `meta`.

Partial updates

PATCH changes only what you send. A field you leave out keeps its value; a list you send replaces that list entirely rather than merging into it.

Timestamps are ISO 8601

With an offset, in UTC. `createdAt` and `updatedAt` are on every object that has them.

Absent is not null

A relation you did not ask for is missing from the response rather than null — `steps` is absent from a listing, not empty. Check for the key, not for a value.

Your access, exactly

A token carries the permissions of the person who made it, and every request is authorised per record by the same policies the app uses. There is no token that sees more.

Follow `links.next` until it is null rather than counting pages yourself — that way a page arriving while you read does not make you miss a row or fetch one twice.

• 400 The request itself was malformed — usually a body that is not valid JSON.
• 401 No token, a token that has been revoked, or one sent in the wrong header.
• 403 A real token, but not for this. A recipe shared with you can be read and edited; it cannot be deleted. A viewer cannot compile a book.
• 404 No such id — or an id belonging to somebody else, which answers the same way on purpose. Told apart, an id becomes a way to probe for other people's recipes.
• 405 The right path, the wrong verb.
• 422 Understood and refused. `errors` names the fields and says what was wrong with each.
• 500 Ours. Worth retrying once; if it persists, it is a bug rather than your request.

{
    "message": "The name field is required.",
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}