RESTful API Design Questions

Direct answer. GET, HEAD, and OPTIONS are safe (they must not change server state) and idempotent (calling them N times has the same effect as calling them once). PUT and DELETE are idempotent but not safe. POST is neither safe nor idempotent by default. PATCH is technically unspecified but should usually be treated as non-idempotent unless you deliberately design it to be. Cacheability tracks safety closely but is not identical to it: GET and HEAD are cacheable by default, OPTIONS is safe but has no real caching convention, and none of PUT, DELETE, POST, or PATCH are cacheable by default.

The full classification.

Why cacheability does not just follow safety. GET and HEAD are cacheable by default because a cache can reuse their response without risking a stale side effect, the same property that makes them safe in the first place. OPTIONS is also safe, but nothing about discovering allowed methods or a CORS preflight benefits from caching the way a resource representation does, so there is no real caching convention for it in practice. POST responses CAN technically be cached per the HTTP spec if the response carries explicit freshness information (Cache-Control or Expires), but this is rarely implemented, so treat POST as effectively not cacheable. PUT, DELETE, and PATCH have no meaningful default caching semantics either: caching the result of a mutation makes little sense when the whole point of the call was to change state.

Why this matters beyond vocabulary. Idempotency is the property that makes retries safe. If a client's network call to a PUT times out and it retries, the end state is identical whether the first request actually landed or not, because PUT is defined as "the resource now looks like this", not "apply this delta". A POST retried the same way can create two resources, because POST means "do this action again", and doing a creation action twice creates two things. Safety is what a cache, a browser prefetcher, or a crawler relies on: none of them should ever issue a POST speculatively, because a safe method is one where the caller assumes no side effect happened.

A real bug from getting this wrong. A checkout flow implemented "add item to cart" as a GET request (because it was convenient to trigger from a link). A corporate web-security scanner crawled every link on the page, including that one, adding dozens of items to real users' carts, because the scanner (correctly, per the HTTP contract) assumed GET was safe to call without consequence. The fix was not to block the scanner, it was to make cart mutation a POST, which is exactly what the safety property exists to protect against.

Trade-offs and pitfalls. The subtlest mistake is assuming PATCH is idempotent by default. A PATCH body of {"counter": "increment"} is not idempotent (retrying it increments twice); a PATCH body of {"counter": 5} (set to an absolute value) is. The method name alone does not tell a client which one they are getting, so this needs to be documented per endpoint, not assumed from the HTTP verb.

Direct answer. Malformed JSON is 400 Bad Request. A business-rule validation error is also 400 (or 422 Unprocessable Entity if you distinguish syntactically-valid-but-semantically-wrong from not-even-parseable). An authentication failure (no or invalid credentials) is 401 Unauthorized. An authorization failure (valid credentials, insufficient permission) is 403 Forbidden. A missing resource is 404 Not Found. Work accepted for asynchronous processing is 202 Accepted. A successful creation is 201 Created; a successful update with nothing new to return is 200 OK (or 204 No Content if the body is genuinely empty).

Working through the scenario.

1. Malformed JSON in the request body: the server never even got a well-formed request to evaluate, so this is a client error before any business logic runs. 400.
2. A validation error on a business rule (say, a date field that must not be in the past): the JSON parsed fine, but the content violates a rule. 400 is defensible; many APIs use 422 specifically to separate "your request is not even shaped right" from "your request is shaped right but the values are invalid." Pick one convention and apply it consistently across the whole API.
3. Authentication failure: 401, and the response should include a WWW-Authenticate header naming the expected scheme.
4. Authorization failure: 403. The distinction from 401 matters for the client: 401 means try again with different credentials, 403 means these credentials are fine, you just cannot do this.
5. Resource not found: 404. For a public API, be deliberate about whether a 404 for does-not-exist versus exists-but-you-cannot-see-it leaks information; many APIs intentionally return 404 for both to avoid confirming a private resource's existence to an unauthorized caller.
6. Accepted for async processing: 202, ideally with a Location header pointing at a status resource the client can poll.
7. Successful creation vs. update-with-nothing-new: 201 with the new resource's URI in Location for creation; 200 with a body, or 204 with no body, for an update, depending on whether you have anything useful to return.

Common mistake. Returning 200 for every successful outcome regardless of what actually happened, including creations (should be 201) and validation failures caught late in a handler (silently returning {"success": false} with a 200 status). This breaks every generic HTTP client, cache, and monitoring tool that reasons about status codes rather than parsing your custom body shape, and it is one of the most common REST code-review findings.

Trade-offs and pitfalls. 401 vs. 403 is the pair engineers mix up most: 401 always means I do not know who you are, or I do not believe your credentials; 403 always means I know exactly who you are, and the answer is still no.