HTTP and REST API design
HTTP is the request–response protocol of the web. REST is a style of API design built around resources (nouns) and standard methods (GET, POST, PUT, PATCH, DELETE).
Why it matters
Clients and servers are often built by different teams, or even different companies. They need a clear, stable contract for asking and answering; otherwise every change breaks somebody.
The idea
A good API is predictable. Resources have clear URLs like /users/42/orders, methods mean what they say, and status codes tell the client what happened. Lists are paginated, the API is versioned, and requests that may be retried are made idempotent so a retry can't do the work twice.
A restaurant menu with clear sections. You ask for a dish by name (the resource), say what you want done (the method), and the waiter replies 'served', 'out of stock' or 'not on the menu' (the status code).
A waiter can improvise. An API is a contract: once apps depend on it, you can't change it freely, which is why versioning matters.
How it works
- Name resources as nouns: /users, /users/42, /users/42/orders. Avoid verbs in URLs, like /getUserOrders.
- Choose the method by intent: GET to read, POST to create, PUT to replace, PATCH to change part, DELETE to remove.
- Return a status code that tells the truth: 201 after creating, 400 for bad input, 404 when something is missing, 409 for a conflict, 429 when rate-limited, 500 when the server broke.
- Paginate lists: return 20 items plus a cursor; the client sends the cursor back to get the next 20.
- Make retries safe: the client sends an Idempotency-Key header with POST; the server stores the key with the result and returns the same result if the key comes again.
- Version from day one: /v1/. When you must break something, add /v2/ and keep /v1/ running for old clients.
Example
GET /v1/orders?limit=20&cursor=abc returns 200 OK with 20 orders and a cursor for the next page. POST /v1/orders with an Idempotency-Key header returns 201 Created; retrying with the same key returns the same order instead of creating a second one.
Key points
- Methods: GET reads (safe), POST creates, PUT replaces, PATCH changes part, DELETE removes. GET, PUT and DELETE should be idempotent.
- Status codes: 2xx success (200, 201), 3xx redirect (301, 302), 4xx client error (400, 401, 403, 404, 409, 429), 5xx server error (500, 503).
- Pagination: offset (simple, but slow and unstable on big, changing lists) or cursor (fast and stable; preferred at scale).
- Idempotency key: the client sends a unique key so a retried request isn't processed twice. Essential for payments.
- Versioning: /v1/ in the path or a header, so old clients keep working.
- Alternatives: GraphQL (the client chooses the fields it wants) and gRPC (fast, typed calls between services).
Trade-offs
- REST: simple and cacheable, but may need several calls per screen.
- GraphQL: flexible queries, but harder caching and rate limiting.
- gRPC: fast and strongly typed, but less browser-friendly.
Common mistakes
- Returning 200 OK with an error message hidden in the body.
- Using GET for actions that change data (crawlers and browser prefetching may call it).
- No pagination, so one request can return a million rows.
- Breaking changes without a new version.
Not true: Errors: return 200 OK and describe the problem in the body.
In fact: Clients, proxies and monitoring tools read the status code. Use 4xx for a client's mistake and 5xx for a server failure, so that errors can be seen.
Not true: GET: fine for an action that changes data, such as deleting a row.
In fact: GET must be safe: crawlers and browser prefetching may call it at any time. Use POST, PUT, PATCH or DELETE for changes.
In the interview
I'd design the API around resources, with standard methods and status codes. I'd paginate lists with cursors and version the API. I'd also require an idempotency key on any create or payment endpoint, so client retries are safe.
Part of Unit 1: Networking and APIs in the free System Design course.