RESTful Architecture: Principles, API Design, and Interview Notes

These notes summarise the RESTful architecture material: what REST is, how to design good REST APIs, and how to talk about REST in system‑design and interview settings.

1. What is REST?

REST (Representational State Transfer) is an architectural style for networked applications, not a protocol or standard. Most RESTful APIs run over HTTP and treat resources as the main abstraction:

A resource is anything addressable by a URI (user, order, file, etc.).
Clients manipulate resources through representations (usually JSON).
The server is stateless between requests; each request must contain all necessary context.

2. REST architectural constraints

REST is defined by several constraints:

Client–server
- Separate concerns: client handles UI/UX, server handles data and business logic.
Stateless
- No server‑side session. Each request is self‑contained (auth token, parameters, etc.).
- Enables easy scaling and simpler failure handling.
Cacheable
- Responses indicate whether they can be cached (Cache-Control, ETag, etc.).
- Caching improves latency and reduces load.
Uniform interface
- Resources identified by URIs.
- Standard methods (HTTP verbs) and representations.
- Self‑describing messages (headers describe how to parse and handle).
- HATEOAS: hypermedia links guide clients to next actions.
Layered system
- Clients cannot tell if they’re talking to the origin server or an intermediary (proxy, gateway, cache).
- Enables load balancers, reverse proxies, and gateways.
Code on demand (optional)
- Server can send executable code (e.g. JavaScript) to extend client behaviour.

3. HTTP methods and resource modeling

A RESTful API models resources with nouns and uses HTTP methods for actions:

GET /users – list users (read).
POST /users – create a user.
GET /users/{id} – fetch a specific user.
PUT /users/{id} – full update (replace).
PATCH /users/{id} – partial update.
DELETE /users/{id} – delete.

Guidelines:

Use nouns in URIs (/orders, /users/{id}/orders), not verbs like /getUsers.
Use hierarchies to show relationships: /users/{userId}/orders/{orderId}.
Avoid encoding operations in URLs (/activateUser); instead use resource state or sub‑resources (/users/{id}/activation).

4. Status codes and error handling

Use standard HTTP status codes to signal outcomes:

2xx success – 200 OK, 201 Created, 204 No Content.
4xx client errors – 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 429 Too Many Requests.
5xx server errors – 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.

Return a structured error body, e.g.:

{
  "code": "VALIDATION_ERROR",
  "message": "email is invalid",
  "details": { "field": "email" }
}

Consistent error formats make debugging and client integration easier.

5. Idempotency and safety

Safe methods do not change server state (GET, HEAD, OPTIONS).
Idempotent methods can be called multiple times with the same effect (GET, PUT, DELETE, sometimes PATCH).
POST is not idempotent by default.

Why it matters:

Clients and proxies can retry idempotent operations without fear of duplicating work.
For non‑idempotent operations (e.g. payments), use idempotency keys or specific design to make them effectively idempotent.

6. Versioning strategies

APIs evolve; you need a plan for backward compatibility:

URL versioning: /api/v1/users. Simple and visible.
Query parameter: /api/users?version=1.
Header‑based: Accept: application/vnd.myapi.v1+json.

Rules of thumb:

Prefer backward‑compatible changes (add fields, don’t remove or change semantics).
Use deprecation notices before removing old versions.

7. Security basics

Common practices:

HTTPS everywhere – encrypt all traffic.
Authentication and authorization – OAuth2, OIDC, JWT, API keys.
Input validation and output encoding – prevent injection, XSS, etc.
Rate limiting and throttling – protect from abuse and DoS.
CORS – control which domains can call your API.

For interviews: be ready to explain how OAuth2 flows, how JWT is used in Authorization: Bearer ..., and how you’d secure a public vs internal API.

8. REST API design checklist

Resource modeling
- Clear nouns and hierarchy.
- Consistent naming (/users, not /Users).
HTTP semantics
- Correct methods, status codes, and use of headers.
- Support pagination, filtering, and sorting via query parameters.
Pagination
- Offset/limit: ?limit=50&offset=100.
- Page/size: ?page=2&size=50.
Cursor‑based for large datasets: ?cursor=abc123.
Content negotiation
- Content-Type for request body.
- Accept for response format (e.g. application/json).
Documentation
- OpenAPI/Swagger, Postman collections, examples for each endpoint.

9. Example REST workflow (user resource)

Create user
- POST /users → 201 Created + Location: /users/123.
Get user
- GET /users/123 → 200 OK + JSON representation.
Update user
- PUT /users/123 or PATCH /users/123 → 200 OK.
Delete user
- DELETE /users/123 → 204 No Content.

This pattern generalises to most CRUD‑style resources.

10. REST interview highlights (cheat sheet)

Typical areas interviewers probe:

REST fundamentals
- What is REST? What are its constraints?
- Difference between REST and SOAP / GraphQL.
HTTP and semantics
- Methods, status codes, idempotency, safety.
- How to design a REST API for a given domain (e.g. blogging platform).
Best practices
- Pagination, filtering, sorting, error handling, documentation.
- API versioning and backward compatibility.
Security
- OAuth2 vs JWT, how to secure endpoints, rate limiting and CORS.
- Handling secrets and protecting sensitive data.
Performance & scalability
- Caching (ETag, Cache‑Control), gzip, connection reuse.
- Load balancing and API gateways.

Use this as a front page to your more detailed Q&A notes: skim this before interviews, then dive into specific question sets when you need depth.

quyennv.com