REST API interview revision notes

What is REST?

Simple real-life example (Understand first — very important for understanding)

• Think of a library: you ask for a book by its ID, you add a new book, you update a record, or you remove one—each action has a clear, standard meaning.
• REST is a set of conventions so that APIs work in a similar, predictable way using HTTP.

Real-world idea: REST is a style of building APIs where you treat everything as resources (nouns) and use standard HTTP methods and status codes so clients and servers agree on how to talk.

Technical definition

• REST = Representational State Transfer; an architectural style for networked APIs.
• Resources are identified by URLs (nouns); actions are expressed with HTTP methods (GET, POST, PUT, PATCH, DELETE).
• Stateless: each request carries everything the server needs; no session stored on server.

Simple practical example

GET /users returns a list; GET /users/1 returns one user; POST /users creates one; PUT /users/1 updates; DELETE /users/1 removes.

Code example

// REST-style endpoints
app.get('/users', listUsers);
app.get('/users/:id', getUser);
app.post('/users', createUser);
app.put('/users/:id', updateUser);
app.delete('/users/:id', deleteUser);

Why it matters

REST is the most common API style. Understanding resources, methods, and statelessness is expected in backend and full-stack interviews.

Interview tip

Say: "REST uses URLs for resources and HTTP methods for actions; it's stateless and uses standard status codes. I design APIs around nouns and verbs (methods)."

HTTP methods (GET, POST, PUT, PATCH, DELETE)

Simple real-life example (Understand first — very important for understanding)

• GET: "Give me this" — you don't change anything; safe to repeat.
• POST: "Here is something new" — create or submit data.
• PUT/PATCH: "Update this" — PUT often replace whole; PATCH partial update.
• DELETE: "Remove this."

Real-world idea: the HTTP method tells the server what kind of action you want. Using the right method keeps the API clear and predictable.

Technical definition

• GET: read; should be safe and idempotent; no body (or ignored).
• POST: create or non-idempotent action; body often JSON.
• PUT: replace resource (full update); idempotent.
• PATCH: partial update; idempotent when applied to same state.
• DELETE: remove resource; idempotent.

Code example

GET    /users        → list
GET    /users/1      → get one
POST   /users        → create (body: { name, email })
PUT    /users/1      → replace (body: full user)
PATCH  /users/1      → partial update (body: { name })
DELETE /users/1      → delete

Why it matters

Using methods correctly affects caching, retries, and how clients and proxies behave. Interviewers often ask the difference between PUT and PATCH.

Interview tip

Explain safe (GET) vs non-safe, idempotent (GET, PUT, DELETE) vs non-idempotent (POST), and when you'd use PATCH instead of PUT.

Resources & URL design

Simple real-life example (Understand first — very important for understanding)

• Like addresses: /building/floor/room — you name the thing (resource), not the action.
• Actions come from the HTTP method; the URL says what you're talking about.

Real-world idea: URLs should name resources (nouns), be hierarchical where it makes sense, and stay consistent so the API is easy to learn and use.

Technical definition

• Use nouns (plural often for collections): /users, /orders, /products.
• Hierarchy for relationships: /users/1/orders, /orders/1/items.
• Avoid verbs in URL: prefer PUT /users/1 over POST /users/1/update.
• Keep URLs stable; version if needed (e.g. /v1/users).

Code example

// Good: resource-based
/users
/users/1
/users/1/orders
/orders/1/items

// Avoid: verb in URL
/getUser/1
/createUser

Why it matters

Good URL design makes the API self-describing and easier to document, test, and consume.

Interview tip

Give examples of resource-based URLs and explain why you avoid verbs in the path.

HTTP status codes

Simple real-life example (Understand first — very important for understanding)

• Like feedback from a counter: "Here’s your order" (200), "We created it" (201), "Wrong request" (400), "Not found" (404), "Server error" (500).
• The number tells the client in a standard way what happened.

Real-world idea: status codes are a contract. Clients and tools rely on them for retries, error handling, and caching.

Technical definition

• 2xx success: 200 OK, 201 Created, 204 No Content.
• 3xx redirect: 301/302 redirect, 304 Not Modified (cache).
• 4xx client error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity.
• 5xx server error: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.

Code example

res.status(201).json({ id: newUser.id, name: newUser.name });
res.status(400).json({ error: 'Invalid email' });
res.status(404).json({ error: 'User not found' });
res.status(500).json({ error: 'Internal server error' });

Why it matters

Using the right status code helps clients handle errors and success correctly; wrong codes break assumptions and tooling.

Interview tip

Know 200, 201, 204, 400, 401, 403, 404, 409, 422, 500 and when to use each. Mention 401 vs 403 (auth vs permission).

Request/response headers (Content-Type, Accept, Authorization)

Simple real-life example (Understand first — very important for understanding)

• Content-Type: "I'm sending you JSON" or "I'm sending form data."
• Accept: "I'd like the response in JSON" (or XML, etc.).
• Authorization: "Here is my credential" (e.g. Bearer token).

Real-world idea: headers describe the body and the client's preferences and carry auth so the server knows how to parse and respond.

Technical definition

• Content-Type: media type of the body (e.g. application/json, application/x-www-form-urlencoded).
• Accept: what media types the client accepts for the response.
• Authorization: Bearer <token>, Basic <base64>, or API key in header.
• Other common: Accept-Language, Cache-Control, If-None-Match (ETag).

Code example

// Client sends
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJhbGc...

// Server sets
Content-Type: application/json
Cache-Control: no-store

Why it matters

Correct headers avoid parsing errors, support content negotiation, and are required for secure auth.

Interview tip

Explain Content-Type vs Accept and how you send a JWT (Authorization: Bearer <token>).

Idempotency & safety

Simple real-life example (Understand first — very important for understanding)

• Safe: reading a page doesn't change anything—you can refresh many times.
• Idempotent: doing the same update twice has the same effect as doing it once (e.g. "set name to X").

Real-world idea: safe and idempotent methods allow clients and proxies to retry or cache without unexpected side effects.

Technical definition

• Safe: GET, HEAD, OPTIONS — no server state change.
• Idempotent: GET, PUT, DELETE, PATCH (when applied to same state) — same request N times = same result as once.
• POST is generally not idempotent (e.g. create twice = two resources); use idempotency keys if needed.

Why it matters

Retries and load balancers rely on these semantics. Designing idempotent APIs reduces duplicate charges or duplicate records.

Interview tip

Define safe and idempotent and give examples. Mention idempotency keys for POST when you need exactly-once semantics.

API versioning

Simple real-life example (Understand first — very important for understanding)

• Like editions of a book: v1 and v2 can coexist so old clients keep working while new ones use the new design.
• You need a clear way to say "I want v2" so the server responds accordingly.

Real-world idea: versioning lets you change the API without breaking existing consumers; you support old and new until clients migrate.

Technical definition

• URL versioning: /v1/users, /v2/users — visible, easy to route.
• Header versioning: Accept: application/vnd.api+v1 — keeps URL clean; less visible.
• Query param: ?version=1 — possible but often discouraged for REST.
• Once chosen, stick to it and deprecate old versions with notice.

Code example

// URL versioning
app.use('/v1', v1Router);
app.use('/v2', v2Router);

// or /api/v1/users

Why it matters

Breaking changes happen; versioning is how you manage them without forcing a big-bang migration.

Interview tip

Compare URL vs header versioning and when you'd use each. Mention deprecation and communication with clients.

Pagination, filtering & sorting

Simple real-life example (Understand first — very important for understanding)

• Like a catalog: "Show page 2," "Only red items," "Sort by price."
• You don't load the whole catalog at once; you ask for a slice and criteria.

Real-world idea: list endpoints should support limits, offsets or cursors, filters, and sort order so clients can build UIs and avoid huge responses.

Technical definition

• Pagination: limit + offset (page, size) or cursor-based (next_cursor, limit) for stable results.
• Filtering: query params (e.g. ?status=active&role=admin) or a small query language.
• Sorting: ?sort=createdAt,-price (asc/desc by convention).

Code example

GET /users?page=2&limit=20&status=active&sort=-createdAt

// Response
{
  "data": [...],
  "total": 100,
  "page": 2,
  "limit": 20
}

Why it matters

Without pagination and filters, list APIs don't scale. This is a standard interview topic for backend design.

Interview tip

Explain offset vs cursor pagination and when you'd use each. Give an example of filter and sort query params.

Error handling & response format

Simple real-life example (Understand first — very important for understanding)

• Like a standard error form: code, message, and optionally which field or request caused it.
• Clients can show a message and optionally highlight the right field.

Real-world idea: consistent error shape and status codes let clients handle failures in one place and give useful feedback to users.

Technical definition

• Use appropriate HTTP status (4xx/5xx); body is still JSON with a consistent shape.
• Common shape: { error: { code, message, details? } } or { success: false, message, errors? }.
• Validation errors: 400 or 422; include field-level errors when useful.

Code example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Why it matters

Predictable error responses simplify front-end logic and improve UX. Interviewers often ask how you'd structure errors.

Interview tip

Describe a consistent error payload and when you'd return 400 vs 422 vs 500.

REST best practices & design tips

Simple real-life example (Understand first — very important for understanding)

• Like writing clear instructions: same format every time, no surprises, and easy to extend later.
• Good REST design feels predictable and easy to document.

Real-world idea: consistency in URLs, methods, status codes, and response shape makes APIs easier to use, test, and evolve.

Technical definition

• Use nouns and HTTP methods correctly; avoid verbs in URLs.
• Return the right status codes and a consistent JSON shape (data + meta/links when useful).
• Support filtering, pagination, and sorting on list endpoints; document limits.
• Use HTTPS; protect sensitive operations with auth; validate input and sanitize output.
• Document with OpenAPI/Swagger or similar; version when you make breaking changes.

Why it matters

These practices reduce bugs and integration cost. They're standard topics in API design discussions and interviews.

Interview tip

Summarize: resource-based URLs, correct methods and status codes, consistent errors and payloads, pagination/filtering, versioning, and security (HTTPS, auth, validation).