REST API Reference

Retrieve a resource. Safe and idempotent — should not modify state.

GET /users/42

Create a new resource or trigger an action. Not idempotent.

POST /users  { name: 'Alice' }

Replace a resource entirely. Idempotent — same result on repeated calls.

PUT /users/42  { name: 'Alice', email: '...' }

Partially update a resource. Only send fields that change.

PATCH /users/42  { email: 'new@mail.com' }

Remove a resource. Idempotent.

DELETE /users/42

Describes the communication options for the target resource.

OPTIONS /users

Like GET but returns only headers, no body.

HEAD /users/42

Request succeeded. Typically used for GET and PUT responses.

Resource created successfully. Return Location header pointing to the new resource.

Request accepted for async processing but not yet completed.

Request succeeded but there is no response body. Common for DELETE.

Resource has permanently moved to a new URL.

Temporary redirect. The resource is currently at a different URL.

Resource has not changed; use the cached version.

Malformed or invalid request syntax.

Authentication is required and has failed or not been provided.

Authenticated but not authorised to access this resource.

Resource does not exist at this URL.

HTTP method is not allowed on this resource.

Request conflicts with the current state of the resource.

Resource has been permanently deleted and will not return.

Request was well-formed but contained semantic errors.

Rate limit exceeded. Include Retry-After header.

Unexpected server-side failure.

Server does not support the functionality required.

Upstream server returned an invalid response.

Server is temporarily unavailable, e.g. during maintenance.

Upstream server did not respond in time.

Use nouns for resources, not verbs. Plural for collections.

/users, /orders/42, /orders/42/items

Version your API to avoid breaking changes.

/v1/users  or  Accept: application/vnd.api+json;version=1

Use limit/offset or cursor-based pagination for large collections.

GET /users?page=2&limit=20  or  ?after=cursor_token

Use query params for filtering and sorting.

GET /users?role=admin&sort=-createdAt

Include hypermedia links in responses to drive state transitions.

{ "id": 1, "links": { "self": "/users/1" } }

For non-idempotent ops, accept an idempotency key header to prevent duplicate execution.

Idempotency-Key: <uuid>

Media type of the request or response body.

Content-Type: application/json

Media types the client can understand.

Accept: application/json

Credentials for authenticating the request.

Authorization: Bearer <token>

URL of created or redirected resource.

Location: /users/42

Version identifier for conditional requests.

ETag: "abc123"

Caching directives for the response.

Cache-Control: max-age=3600, must-revalidate