Code-Memo

HTTP Methods in APIs

GET (read)

  1. Safe (should not change server state) and commonly cacheable when response headers allow.
  2. Must not carry a body with semantics in many stacks; use query parameters for filters.
  3. Use 200 with a body, 204 for no content, or 404 when the resource is missing (be consistent across the API).

POST (create)

  1. Used to create resources or trigger non-idempotent processing (side effects, workflows).
  2. Often returns 201 Created with a Location header pointing to the new resource when applicable.
  3. Not inherently idempotent: retries can duplicate unless you add idempotency keys or de-duplication.

PUT vs PATCH (update differences)

  1. PUT: replace the entire resource representation the client sends; idempotent when the server interprets it as “set state to this.”
  2. PATCH: partial update (JSON Merge Patch, JSON Patch, or custom schema); define semantics clearly to avoid ambiguous merges.
  3. If clients cannot send full objects, PATCH (or POST to a sub-resource) is usually clearer than overloading PUT.

DELETE (remove)

  1. Should remove or soft-delete consistently; document whether deletes are recoverable.
  2. Often idempotent: deleting twice yields the same end state (204 or 404 after gone).
  3. Consider async deletion for heavy resources (202 + job id) when work cannot finish inline.

Idempotency concept

  1. Idempotent methods can be repeated safely: same outcome (GET, PUT with stable ids, DELETE).
  2. POST is the usual place where idempotency matters most; use Idempotency-Key headers or natural keys.
  3. Document how long idempotency records are retained and what happens on conflict.