Grokking Modern API Design Interview
Vote

0% completed

​

What Are REST APIs?

  1. The Problem REST Solves
  1. Resources and Representations
  1. The Uniform Interface
  1. URLs Identify, Methods Act
  1. Every Request Stands Alone
  1. Why REST Became the Default
  1. A Resource Is Not a Database Table
  1. What REST Is Not
  1. The Vocabulary

Key Takeaways

Two teams build the same feature: let a customer cancel an order.

The first team publishes POST /cancelOrder. The second publishes PATCH /orders/ord_7M2K carrying {"status": "cancelled"}.

Both work on the first day. A year later the first team has published /cancelOrder, /uncancelOrder, /cancelOrderItem, and /getCancellationStatus, and a caller must read documentation before every one of them. The second team still has one noun and a method vocabulary its callers already knew.

REST is the set of conventions that produces the second outcome.

REST is a set of conventions in which the things a caller acts on are given stable URLs, and callers act on them through a small, fixed set of HTTP methods.

The name is short for representational state transfer. The full academic form describes several constraints on how networked software should be built. This course uses its practical core, which is what interviews actually test.

1. The Problem REST Solves

Without a shared vocabulary, an API designer invents a new name for every behavior:

/createDocument
/fetchDocument
/changeDocumentTitle
/removeDocument

Each name is understandable by itself. Together they force the caller to memorize four unrelated commands, and a fifth behavior needs a fifth invented name. Nothing in the existing contract tells the caller whether the next one will be /updateDocument, /modifyDocument, or /editDocumentDetails.

Adding the fifth behavior to each contract. A verb API needs a newly invented name and raises questions the documentation must answer separately: is it issueRefund, refundOrder, or createRefund, and which method does it use? A resource API reuses one noun and a fixed method vocabulary, so the refund becomes a sub-resource under the order.
Adding the fifth behavior to each contract. A verb API needs a newly invented name and raises questions the documentation must answer separately: is it issueRefund, refundOrder, or createRefund, and which method does it use? A resource API reuses one noun and a fixed method vocabulary, so the refund becomes a sub-resource under the order.

REST replaces most of that invention with two small vocabularies. The first is made of resources, the things a caller can name and act on. The second is made of HTTP methods, a small set of standard actions whose meanings are reused across every resource.

POST /documents
GET /documents/doc_7M2K
PATCH /documents/doc_7M2K
DELETE /documents/doc_7M2K

The design work does not disappear. It moves to the decisions that matter: whether a refund deserves its own identity, whether cancellation is a state change or a separate record, which fields may change, and what happens when an order has already shipped. Choosing between five synonyms for "get" is not one of those decisions.

2. Resources and Representations

A resource is a thing the API names: an order, a document, a saved article, one user's reading list. It has a stable identity that survives changes to its contents.

A representation is what actually travels over the network. The resource is the concept; the representation is one rendering of its current state, usually a JSON object:

{
  "id": "doc_7M2K",
  "title": "Launch checklist",
  "status": "draft",
  "updated_at": "<RFC 3339 UTC timestamp>"
}

The distinction matters more than it first appears. One resource can have several representations: a summary in a list, and a full body on a direct read. The resource keeps its identity while its representation changes on every edit. When later lessons say a response is a caller-visible contract, they mean the representation.

3. The Uniform Interface

The methods are the fixed part. A caller who has learned them for one resource has learned them for every resource in the API, and for most other REST APIs as well.

The five HTTP methods and what each one means: GET reads and changes nothing, POST asks a collection for a new member and may create two if sent twice, PUT sends a whole new representation and leaves one result, PATCH sends only the fields that change, and DELETE asks for the member to be absent. The same five meanings apply to every resource in the API.
The five HTTP methods and what each one means: GET reads and changes nothing, POST asks a collection for a new member and may create two if sent twice, PUT sends a whole new representation and leaves one result, PATCH sends only the fields that change, and DELETE asks for the member to be absent. The same five meanings apply to every resource in the API.

Those five are the whole action vocabulary. A product with forty resources still uses these five, which is why a caller can predict an operation they have never read. Lesson 4 designs each one in full, including the promises they make when a request is delayed, repeated, or retried.

4. URLs Identify, Methods Act

The two halves of a request answer different questions. The URL says which thing the caller is addressing. The method says what kind of interaction the caller wants. Headers, query parameters, and the body supply the rest.

One request split into its two questions. The method answers what kind of interaction is wanted and the URL answers which thing is addressed. Below them, the two URL shapes that cover most of an API: a collection names a set and supports listing and creation, while a member names one resource inside it and supports reading, changing, and removal.
One request split into its two questions. The method answers what kind of interaction is wanted and the URL answers which thing is addressed. Below them, the two URL shapes that cover most of an API: a collection names a set and supports listing and creation, while a member names one resource inside it and supports reading, changing, and removal.

Two URL shapes cover most of an API. A collection names a set of resources and supports listing and creation. A member names one resource inside that collection and supports reading, changing, and removal.

GET  /orders                 the collection
POST /orders                 create a member in it
GET  /orders/ord_7M2K        one member

The identifier belongs in the path because it is part of the member's identity. Values that filter, sort, or page the same collection belong after the question mark, because they select from a set rather than name a thing. Lesson 5 develops that rule.

5. Every Request Stands Alone

A REST request carries everything the server needs to understand it. The server does not remember that this caller read an order two requests ago and is therefore "in" some conversation.

This has one visible consequence for a caller: authentication travels on every request rather than being established once. It has a larger consequence for the provider: because any server can answer any request, capacity can be added without callers noticing any change.

Statelessness is about the protocol, not about data. The server obviously stores orders. What it does not store is a per-caller conversation position that the next request depends on.

6. Why REST Became the Default

REST is this course's default for four practical reasons.

Most callers already understand its model. Browsers, mobile applications, partner servers, command-line tools, proxies, and monitoring systems all speak HTTP. In an interview, that means you and the interviewer can discuss the contract directly, without first agreeing on how calls travel.

Existing software understands method and status meanings. SDKs, caches, proxies, retry libraries, gateways, and observability tools inspect the method and the status code. When you use GET, you promise the call is a read. When you return 429, a caller knows a published rate limit was reached. Standard meanings let software decide correctly without parsing prose documentation.

Constraints create consistency. A small vocabulary forces related operations to resemble one another, so every new operation costs the caller less to learn.

It is visible. A developer can read a REST request and its response without generated code, which shortens both integration and incident response.

Four practical reasons REST is the default, each with what it gives: callers already understand HTTP so there is no new client model to teach, existing software reads method and status meanings so it behaves correctly without reading prose, a small vocabulary forces consistency so each new operation costs less to learn, and requests are readable without generated code.
Four practical reasons REST is the default, each with what it gives: callers already understand HTTP so there is no new client model to teach, existing software reads method and status meanings so it behaves correctly without reading prose, a small vocabulary forces consistency so each new operation costs less to learn, and requests are readable without generated code.

None of that makes REST the best fit for every job. A browser that only needs live server updates may use Server-Sent Events. A high-volume internal service may benefit from gRPC. Clients that need very different field sets may justify GraphQL, and work that takes minutes should become a job resource. Chapter 3 covers each of those, and this course applies one rule whenever it leaves REST:

Name the trigger that makes REST a poor fit, and name the cost of the alternative.

7. A Resource Is Not a Database Table

REST's focus on resources creates one dangerous misunderstanding: candidates hear "resource" and expose every table as a URL.

A table is chosen to store data efficiently. A resource is chosen because it gives the caller a useful, stable thing to act on. One resource may combine several tables, one table may support several resources, and a resource such as a home timeline may not be stored as a row at all. Storage may move from one database to several services, and the resource should stay the same as long as the caller's model of the product has not changed.

Use this test:

"Would I still publish this resource if the implementation stored the data in a completely different way?"

If the answer is no, you may be publishing storage rather than a contract.

8. What REST Is Not

It is not "JSON sent over HTTP." An API can send JSON over HTTP and still publish /doDocumentAction. REST is the discipline of giving resources stable identities and applying standard method meanings consistently.

It does not require every behavior to be create, read, update, or delete. Products cancel orders, publish documents, and recalculate reports. Lesson 3 shows where those actions go, and a verb-shaped operation is a legitimate last resort when no resource model fits.

It is not a score to maximize. The goal is not the most RESTful URL anyone could design. The goal is the smallest predictable contract that finishes the caller's job.

9. The Vocabulary

These words appear in every remaining lesson of the course.

The REST vocabulary used through the rest of the course, each term with a plain definition and an example: resource, representation, collection, member, sub-resource, method, safe, idempotent, and uniform interface.
The REST vocabulary used through the rest of the course, each term with a plain definition and an example: resource, representation, collection, member, sub-resource, method, safe, idempotent, and uniform interface.

Key Takeaways

  • REST is a set of conventions in which the things a caller acts on get stable URLs, and callers act on them through a small, fixed set of HTTP methods.
  • It exists to replace invented per-behavior operation names with two small vocabularies, so a caller who has learned two operations can predict the third.
  • A resource is the thing the API names; a representation is one rendering of its current state that actually travels over the network.
  • The uniform interface is GET, POST, PUT, PATCH, and DELETE, and their meanings are the same for every resource.
  • The URL identifies which thing; the method says what kind of interaction. A collection names a set, and a member names one resource inside it.
  • Every request carries what the server needs to understand it, so credentials travel on each one and any server can answer any request.
  • REST is the default because it is widely understood, machine-readable, consistent, and visible, not because it fits every kind of work.
  • A resource is a caller-facing product concept, not a public copy of a storage table.
  • REST is not merely JSON over HTTP, does not require every behavior to be CRUD, and is not a score to maximize.

You now have the vocabulary the rest of the course assumes. The next lesson sets out what this chapter builds with it: the decisions that turn a caller's job into resources, operations, and one complete contract.

On This Page

  1. The Problem REST Solves
  1. Resources and Representations
  1. The Uniform Interface
  1. URLs Identify, Methods Act
  1. Every Request Stands Alone
  1. Why REST Became the Default
  1. A Resource Is Not a Database Table
  1. What REST Is Not
  1. The Vocabulary

Key Takeaways