code-review-api

Code Review — REST / HTTP API Layer

Focus on correctness, consistency, and safety at the HTTP boundary.

---

HTTP Semantics

• Correct status codes — 201 Created for POST that creates; 200 OK for updates; 204 No Content for DELETE; 400 Bad Request for invalid input; 404 Not Found for missing resources; 409 Conflict for duplicate creation; 422 Unprocessable Entity for validation failures; 500 Internal Server Error for unhandled exceptions.
• Non-idempotent PUT — PUT must be idempotent (same request = same result). If the operation has side effects that shouldn't repeat, it should be a POST.
• DELETE returns a body — RFC 7231 allows it, but clients often discard it. Prefer 204 No Content unless returning the deleted resource is explicitly needed.
• Wrong method for the operation — using GET for state-changing operations (no caching, logging of query params); using POST when PUT/PATCH is more appropriate.

---

Input Validation & Error Shapes

• Missing input validation — user-supplied fields used directly without type/range/pattern validation. Every boundary input must be validated before use.
• Inconsistent error shape — some errors return {"error": "..."}, others {"message": "..."}. The API should follow one schema (RFC 9457 Problem Details recommended).
• Stack trace in production response — never send exception stack traces to clients. Log server-side; return a stable error code.
• Leaking internal IDs — returning auto-increment integer IDs exposes row count; prefer UUIDs or opaque tokens.

---

Authentication & Authorization

• Auth happens after the operation — authorization must be checked before the DB query, not after loading the resource.
• Missing ownership check — user can access /orders/123 even if order 123 belongs to another user. Every resource access needs an ownership/permission check.
• Token in URL — never put auth tokens in query strings (they appear in logs, referrer headers, browser history). Use Authorization header.
• Missing rate limiting — unauthenticated endpoints or auth endpoints (login, signup) with no rate limit are trivially brute-forced or scraped.