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 approaches can work. However, separately naming every action can make an API harder to learn as it grows. A resource-oriented design can reuse familiar methods across many operations. Cancellation still needs explicit rules; a PATCH request is not automatically the best design for every product.

REST provides a resource-oriented approach to these design decisions.

REST, short for representational state transfer, is an architectural style for networked systems. In HTTP APIs, a common practical approach is to identify resources with URLs and use standard HTTP methods to interact with them.

The full REST style includes client-server separation, stateless requests, cache rules, a uniform interface, and layers; downloadable code is optional. Its uniform interface also includes resource representations, self-describing messages, and links that guide available actions. This course mainly uses the common resource-oriented HTTP API conventions, rather than covering every REST constraint in depth.

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, but the API needs a separate naming rule for every action. Without consistent conventions, clients cannot predict whether another update will be called 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

You still need to decide whether a refund needs its own identity, whether cancellation changes an order or creates a separate record, which fields can change, and what happens after shipment. Shared method conventions let you focus on these behaviors.

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>"
}

One resource can have several representations, such as a summary in a list and a detailed response when read directly. Its identity stays the same even when its fields change. Representations are part of the API contract, along with status codes, headers, and behavior.

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.

Five common HTTP methods. GET requests a representation without requesting a state change. POST performs resource-specific processing, often creation. PUT creates or replaces state at a known URL. PATCH applies changes using a defined format. DELETE removes the resource's association with its URL. The API must define which methods it supports.
Five common HTTP methods. GET requests a representation without requesting a state change. POST performs resource-specific processing, often creation. PUT creates or replaces state at a known URL. PATCH applies changes using a defined format. DELETE removes the resource's association with its URL. The API must define which methods it supports.

These are five methods commonly used in resource-oriented APIs, not all HTTP methods. For example, HTTP also defines HEAD and OPTIONS. An API supports only the methods appropriate for each resource. Lesson 4 explains method behavior, including what happens when a request is repeated.

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.

Each protected request includes authentication information; it should not depend on a previous request having selected a user or resource. This makes it easier to route requests between server instances. Those instances must still have access to the necessary data and configuration.

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. Clients, caches, proxies, and monitoring tools use HTTP methods, status codes, and headers to interpret requests. GET asks to read a resource without requesting a state change. 429 reports that the client has sent too many requests. The API must still define details such as retry timing and application errors.

Constraints encourage consistency. Reusing a small set of methods makes related operations easier 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.

REST is not the best fit for every requirement. Server-Sent Events can deliver live updates to a browser. gRPC may suit internal service calls, and GraphQL may help clients request different sets of fields. Long-running work can use job resources within a REST-style API. Chapter 3 explains these options and their costs.

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 an architectural style. This course focuses on common resource-oriented HTTP conventions: stable resource URLs and standard method meanings.
  • 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.
  • GET, POST, PUT, PATCH, and DELETE are common HTTP methods with defined meanings. They are part of a broader uniform interface, not its complete definition.
  • 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, including authentication information when needed. This reduces dependence on a particular server instance.
  • 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.

Reading Progress

0%

Vote for new content

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