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

  1. Name resources as nouns: /users, /users/42, /users/42/orders. Avoid verbs in URLs, like /getUserOrders.
  2. Choose the method by intent: GET to read, POST to create, PUT to replace, PATCH to change part, DELETE to remove.
  3. 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.
  4. Paginate lists: return 20 items plus a cursor; the client sends the cursor back to get the next 20.
  5. 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.
  6. 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

Trade-offs

Common mistakes

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.