Why this matters
Most backend work is moving data over HTTP between clients and services. You will design endpoints, select proper methods, return correct status codes, handle headers, and debug requests quickly. Strong HTTP/REST skills make your services predictable, cacheable, debuggable, and easy for others to integrate.
- Design resource-oriented APIs that frontends and partners can consume.
- Choose correct methods (GET, POST, PUT, PATCH, DELETE) and status codes.
- Use headers for auth, content negotiation, and caching.
- Debug failures fast using request/response structure.
Who this is for
- Aspiring and junior backend engineers who need a solid HTTP/REST base.
- Full‑stack developers who integrate with APIs and want cleaner designs.
- QA and DevOps engineers who test and observe web services.
Prerequisites
- Basic programming skills in any language.
- Able to run a command line tool (e.g., curl) and read JSON.
Learning path
- Requests and responses: methods, status codes, headers, bodies.
- REST resource modeling: nouns, URIs, path vs query params.
- Idempotency, safety, statelessness.
- Pagination, filtering, sorting.
- Caching basics: ETag, Cache-Control; conditional requests.
- Auth at a glance: Authorization header, 401 vs 403.
Concept explained simply
HTTP is a request/response protocol. A client sends a request line, headers, and optionally a body. The server replies with a status line, headers, and optionally a body.
Minimal HTTP flow
GET /products/42 HTTP/1.1
Host: api.example.com
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60
{"id":42,"name":"Mug","price":12.99}
- Methods: GET (read), POST (create/action), PUT (replace), PATCH (partial update), DELETE (remove).
- Status codes: 2xx success, 4xx client error, 5xx server error. Common: 200, 201, 204, 400, 401, 403, 404, 409, 422, 500.
- Headers: metadata. Examples: Content-Type, Accept, Authorization, Cache-Control, ETag, If-None-Match.
- Body: usually JSON for APIs with Content-Type: application/json.
Mental model
Think of each resource as a noun with a stable URL. Methods are verbs applied to that noun. Status codes are short outcomes. Headers are rules and context. Make each endpoint predictable: same input shape, same output shape, same code path per method.
Core building blocks
Resource-oriented design
- Use plural nouns: /books, /books/123, /authors/9/books
- Use query params for filtering/sorting/pagination: /books?authorId=9&limit=20&offset=40
Idempotency and safety
- Safe: GET, HEAD (no server state change).
- Idempotent: GET, PUT, DELETE, HEAD, OPTIONS (same result if repeated).
- POST is neither safe nor idempotent by default. For retriable POST, use idempotency keys.
Caching quickstart
- ETag with If-None-Match enables 304 Not Modified.
- Cache-Control: max-age, no-store, no-cache (revalidate).
- Only cache GET responses.
Auth basics
- Authorization: Bearer <token>
- 401 Unauthorized: no/invalid credentials. 403 Forbidden: authenticated but not allowed.
Worked examples
Example 1: Retrieve a product (GET)
Request:
curl -i \
-H "Accept: application/json" \
https://api.example.com/products/42
Response:
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "p42-v5"
Cache-Control: max-age=60
{"id":42,"name":"Mug","price":12.99}
Conditional GET:
curl -i \
-H "Accept: application/json" \
-H "If-None-Match: \"p42-v5\"" \
https://api.example.com/products/42
Response:
HTTP/1.1 304 Not Modified
Example 2: Create a product (POST)
Request:
curl -i -X POST \
-H "Content-Type: application/json" \
-d '{"name":"Bottle","price":15.50}' \
https://api.example.com/products
Response:
HTTP/1.1 201 Created
Location: /products/43
Content-Type: application/json
{"id":43,"name":"Bottle","price":15.50}
Example 3: Partially update (PATCH)
Request:
curl -i -X PATCH \
-H "Content-Type: application/json" \
-d '{"price":14.99}' \
https://api.example.com/products/43
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{"id":43,"name":"Bottle","price":14.99}
Exercises
Do these now. They mirror the graded tasks below and build the habits you need.
- Exercise 1: Design a small REST API for a library.
- Exercise 2: Debug and fix a failing HTTP request.
Self-check checklist:
- Endpoints use plural nouns and consistent paths.
- Correct methods chosen for each action.
- Appropriate status codes and minimal, readable JSON bodies.
- Headers used correctly (Content-Type, Accept, Authorization if needed).
Common mistakes and how to self-check
- Using verbs in paths (e.g., /createBook). Fix: use nouns and HTTP methods.
- Returning 200 for everything. Fix: use 201 for creation, 204 for no content, 400/404/409 as appropriate.
- Mixing path and query usage. Fix: identifiers in path; filtering/sorting/pagination in query.
- Forgetting Content-Type. Fix: always send Content-Type: application/json for JSON.
- Breaking idempotency of PUT/DELETE. Fix: ensure repeated calls yield the same final state.
Practical projects
Project 1: Read-only catalog API
- Create /items and /items/{id} with GET only.
- Return JSON with id, name, price; add ETag and Cache-Control: max-age=60.
- Support filtering by category: /items?category=mugs and pagination: limit/offset.
Project 2: CRUD with validation
- Add POST /items with 201 Created and Location header.
- Add PUT and PATCH for updates; return 200 with updated JSON or 204 if no body.
- Validate inputs; return 400 with an error object {"error":"..."}.
Project 3: Conditional requests
- Generate ETags for item responses.
- Support If-None-Match for GET (return 304 when unchanged).
- Document examples for clients using curl.
Before you take the quick test
The quick test is available to everyone. Only logged-in users get saved progress.
Mini challenge
Design the endpoints for a ride-sharing app:
- Resources: riders, drivers, rides.
- Paths, methods, and main status codes for: request ride, accept ride, update ride status, get rider ride history.
- Decide what is path vs query. Identify at least one idempotent operation.
Next steps
- Deepen REST design: relationships, error formats, versioning strategies.
- Authentication and authorization patterns (tokens, 401 vs 403 nuances).
- Performance: caching layers, pagination strategies, and rate limiting.