Web APIs · intermediate
HTTP API and REST semantics
An HTTP API exchanges resource representations through standardized request methods, status codes, headers, and caching semantics; REST is an architectural style whose constraints go beyond using JSON over HTTP.
Why it matters
Respecting HTTP semantics makes retries, caches, intermediaries, clients, and observability behave predictably instead of relying on endpoint-specific conventions.
Mental model
How to reason about http api and rest semantics
The URL identifies a target resource, the method states the request semantics, headers carry metadata and conditions, the body carries a representation, and the status describes the outcome.
Analogy
A postal form identifies an address, declares the requested action, encloses a document format, and returns an official outcome code; each field has a shared protocol meaning.
Examples
See the boundary, not just the happy path
Worked example · Conditional update
PUT /documents/7 with If-Match: "v3"The precondition lets the server reject an update when the representation changed, preventing an unnoticed lost update.
Worked example · Create outcome
201 Created with Location: /orders/42The status says a resource was created and Location identifies the newly created resource.
Avoid · State change through GET
GET /accounts/7/deleteGET is defined as safe in intent and may be prefetched, retried, or cached. Using it for deletion violates intermediary and client expectations.
Common mistakes
Misconceptions to remove early
Calling every JSON endpoint REST
REST includes constraints such as stateless interaction, resource-oriented uniform interfaces, and cache semantics. JSON is only a representation format.
Returning 200 for every outcome
Meaningful status codes distinguish creation, no-content success, validation failure, authentication, conflict, not-found, and server failure for generic clients and tooling.
Quick check
Can you predict the result?
1. Why should a GET request not perform a destructive action?
- • GET is safe in intent and may be automatically prefetched, cached, or repeated
- • GET requests cannot include a path
- • Servers are unable to authenticate GET requests
2. What is the role of an If-Match precondition on an update?
Keep building