PUT, PATCH & DELETE

These three methods cover the “U” and “D” of CRUD. The subtle one is the difference between PUT and PATCH — get it right and updates stay predictable.

PUT — full replacement

PUT replaces the resource at a URI with the representation in the body. Send the whole resource; any field you omit is, semantically, being set to absent. Because the result of PUT-ing the same body twice is identical to once, PUT is idempotent.

PUT /articles/42 HTTP/1.1
Content-Type: application/json

{ "title": "Updated title", "body": "Full new body" }

PATCH — partial update

PATCH applies a partial modification. Two common formats:

JSON Merge Patch (application/merge-patch+json): send only the fields to change; null means “remove this field”.
JSON Patch (application/json-patch+json): send an array of explicit operations (add, remove, replace, …).

PATCH is not guaranteed idempotent in general (an op like “append to a list” is not), though many merge-patch updates happen to be.

DELETE — remove

DELETE removes the resource. It is idempotent: deleting an already-deleted resource still leaves it deleted. Return 204 No Content (or 200 OK with a body) on success; a second DELETE may return 204 or 404 depending on your policy — pick one and be consistent.

Update in a running API

JavaScript

const store = new Map([[1, { id: 1, title: 'Original', body: 'Hello' }]]);

// PUT — full replacement (idempotent)
app.put('/articles/:id', async (c) => {
  const id = Number(c.req.param('id'));
  const body = await c.req.json();
  const replaced = { id, title: String(body.title ?? ''), body: String(body.body ?? '') };
  store.set(id, replaced);
  return c.json(replaced);
});

// PATCH — merge only provided fields
app.patch('/articles/:id', async (c) => {
  const id = Number(c.req.param('id'));
  const current = store.get(id);
  if (!current) return c.json({ error: 'Not found' }, 404);
  const patch = await c.req.json();
  const updated = { ...current, ...patch, id };
  store.set(id, updated);
  return c.json(updated);
});

app.delete('/articles/:id', (c) => {
  store.delete(Number(c.req.param('id')));
  return c.body(null, 204); // idempotent
});