Methods & Status Codes

Two small vocabularies do most of the work in a REST API: the handful of HTTP methods that express intent, and the status codes that report outcomes. Learn these well and most design decisions get easier.

The methods

Method	Meaning	Safe	Idempotent
`GET`	Read a resource	yes	yes
`HEAD`	Read headers only	yes	yes
`POST`	Create / submit	no	no
`PUT`	Replace a resource	no	yes
`PATCH`	Partially update	no	no
`DELETE`	Remove a resource	no	yes
`OPTIONS`	Describe what is allowed	yes	yes

Safe means the call has no observable side effects (it only reads). Idempotent means making the same call many times has the same effect as making it once. These two properties drive a lot of correctness: clients and proxies may freely retry safe/idempotent requests, but must be careful retrying a POST.

The status-code families

flowchart TD
  R[Response status] --> I[1xx Informational]
  R --> S[2xx Success]
  R --> RD[3xx Redirection]
  R --> C[4xx Client error]
  R --> SE[5xx Server error]
  S --> S2[200 OK / 201 Created / 204 No Content]
  C --> C2[400 / 401 / 403 / 404 / 409 / 422]
  SE --> SE2[500 / 503]

Five families; in practice you reach for a small subset

The ones you use constantly: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 500 Internal Server Error. The golden rule: a 2xx means the request succeeded, a 4xx means the client must change something, and a 5xx means the server failed.

Methods and statuses in a real API

This Hono app exposes three routes that return different methods and statuses. Open it in StackBlitz to run a real server and hit the endpoints:

JavaScript

// A tiny read-only resource with sensible statuses.
const articles = [{ id: 1, title: 'Hello' }];

app.get('/articles', (c) => c.json(articles)); // 200 OK

app.get('/articles/:id', (c) => {
  const found = articles.find((a) => a.id === Number(c.req.param('id')));
  if (!found) return c.json({ error: 'Not found' }, 404);
  return c.json(found); // 200 OK
});

app.post('/articles', async (c) => {
  const body = await c.req.json();
  const created = { id: articles.length + 1, ...body };
  articles.push(created);
  return c.json(created, 201); // 201 Created
});