Designing and implementing HTTP APIs that follow REST principles: resources, methods, status codes, and idempotency.
Designing and implementing HTTP APIs that follow REST principles: resources, methods, status codes, and idempotency.
Lesson outline
REST (Representational State Transfer) is an architectural style for APIs over HTTP. Resources are identified by URLs (e.g. /users, /users/1). Clients use HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE (delete). Stateless means each request carries everything the server needs; no session stored on the server.
Responses use status codes and a body (usually JSON). The same URL can return different representations (e.g. Accept: application/json vs application/xml). REST does not require a specific format but JSON is the norm for modern APIs.
Use nouns for resources, not verbs: /orders not /getOrders. Nest for hierarchy when it makes sense: /orders/123/items for the items of order 123. Use query parameters for filtering and pagination: ?status=active&page=2&limit=20. Version APIs in the URL (/v1/users) or in a header (Accept: application/vnd.api+v1+json).
Idempotency: GET, PUT, and DELETE are idempotent—sending the same request twice has the same effect as once. POST is not: two identical POSTs typically create two resources. Use PUT for full replacement of a resource, PATCH for partial updates when the semantics are clear (e.g. send only the fields that change).
2xx Success: 200 OK (GET, PUT, PATCH, or successful DELETE with body); 201 Created (POST with Location header pointing to the new resource); 204 No Content (DELETE or PUT/PATCH with no body to return).
4xx Client errors: 400 Bad Request (malformed or invalid input); 401 Unauthorized (not authenticated—missing or invalid token); 403 Forbidden (authenticated but not allowed); 404 Not Found (resource does not exist); 409 Conflict (e.g. duplicate, version conflict); 422 Unprocessable Entity (validation failed). 5xx are server errors; return 500 only when something broke on your side, and never expose internal details.
For POST operations that create resources (e.g. payments), clients may retry on timeout. If the server processes the request twice, you might double-charge. Use idempotency keys: the client sends Idempotency-Key: unique-key-123; the server stores the key and the result. A retry with the same key returns the same result without re-running the operation.
PATCH should accept a partial body (e.g. { "name": "New Name" }) and update only those fields. PUT often replaces the entire resource; if the client sends only a subset, treat missing fields as "clear" or "default" depending on your API contract. Document this clearly.
HATEOAS (Hypermedia as the Engine of Application State) means responses include links to related actions (e.g. "links": { "self": "/orders/1", "cancel": "/orders/1/cancel" }). Clients discover what they can do next from the response. Many REST APIs skip this and rely on documentation; it is useful for highly dynamic or exploratory clients.
From the browser you use fetch() or a library (axios). Send method, headers (Content-Type: application/json, Authorization: Bearer token), and body (JSON.stringify(data)). Handle responses: check response.ok, parse response.json(), and handle errors and loading state.
CORS allows the server to permit requests from other origins. The server sends Access-Control-Allow-Origin (and related headers). For authenticated APIs, use tokens in the Authorization header and refresh them when they expire; store tokens securely (e.g. httpOnly cookie or memory, not localStorage if XSS is a concern).
Use nouns and plural for collections (/users). Use correct methods and status codes. Support pagination for list endpoints. Version the API (URL or header). Validate input and return structured errors. Use HTTPS and authenticate sensitive endpoints. Document with OpenAPI (Swagger) so clients can generate code and test easily.
Related concepts
Explore topics that connect to this one.
Practice with these scenarios
Apply this concept in hands-on scenarios.
Test yourself: 1 challenge
Apply this concept with scenario-based Q&A.
Ready to see how this works in the cloud?
Switch to Career Paths for structured paths (e.g. Developer, DevOps) and provider-specific lessons.
View role-based pathsSign in to track your progress and mark lessons complete.
Questions? Discuss in the community or start a thread below.
Join DiscordSign in to start or join a thread.