0% completed
Introduction: Resource Modeling and REST Core
On This Page
- The Direction Is Fixed
- What Steps 2 and 3 Produce
- An Operation Name Is Not Yet a Contract
- Predictability Is the Design Goal
- The Decisions This Chapter Makes Once
Key Takeaways
Chapter 1 ended with a URL shortener. Step 3 produced this surface in about a minute:
POST /v1/links GET /v1/links/{link_id} GET /v1/links?cursor=...&limit=... DELETE /v1/links/{link_id} GET /v1/links/{link_id}/statistics
Every line there is a decision, and the capstone made all of them without stopping to explain any.
Why is statistics an address of its own rather than a field inside the link? Why POST /v1/links and not POST /v1/createLink? Why does the link id sit in the path while the cursor sits after the question mark? Why does creation answer 201 when a read answers 200?
The previous lesson said what REST is. This chapter gives each of those choices a reason you can say aloud. It also settles the conventions behind them once, so you are not inventing them again in the next interview.
1. The Direction Is Fixed
The six-step method does not change. Chapter 2 goes deep on two of its steps, Resources and Operations, and supplies what Step 4 needs to turn one operation name into a complete contract.
The other steps still run. Step 1 supplies the caller jobs that the resources come from, and Steps 5 and 6 still test whether the design survives failure and whether you can state its cost.
Inside those two middle steps, the order of the decisions matters most.
A caller job becomes a resource, the resource becomes a one-line operation, and the operation becomes a complete contract. Notice what is missing from the start of that line. The database is not on it.
Suppose the service stores tables named customer_rows, purchase_headers, and purchase_lines. Those names describe how the data is kept, not what a caller is trying to finish. The API may combine several tables into one resource, split one table into several, or publish a resource that is calculated and stored nowhere. Storage supports the contract. It does not choose it.
Which nouns survive that first step is the next lesson's question. What matters here is that the question is asked in the caller's language rather than in the language of the schema.
2. What Steps 2 and 3 Produce
Step 1 gives you sentences about what callers need to finish. Steps 2 and 3 turn those sentences into a surface.
Take a small reading-list product. A browser extension saves an article for later. A mobile application lists the reader's saved articles. The reader marks one as finished, and removes another from the list.
Four jobs, four verbs. They do not produce four endpoints.
One resource carries all four. SavedArticle holds an opaque id, the original url, a display title, a status, and RFC 3339 UTC timestamps such as created_at. The reader needs no id anywhere in the path, because authentication already establishes who is calling. The reading list is the collection of one caller's saved articles, so it needs no separate resource of its own.
That produces five one-line operations:
POST /saved-articles GET /saved-articles/{saved_article_id} GET /saved-articles?status=unread&limit=20 PATCH /saved-articles/{saved_article_id} DELETE /saved-articles/{saved_article_id}
It also avoids these:
/saveArticle /markArticleAsFinished /removeArticleFromReadingList
Several caller verbs became one noun and a fixed set of methods. That is the benefit worth naming out loud: a caller who has learned how to change one resource can predict how to change the next one.
3. An Operation Name Is Not Yet a Contract
Step 3 produces one line per operation deliberately. It protects the order of the interview: settle the surface first, then spend Step 4 going deep on a single operation.
POST /saved-articles contains exactly two decisions, a method and a path. It does not say which fields creation requires, what an absent field means in a later patch, what the caller should do when the response is lost, or what the list response holds besides its items.
A complete operation publishes more. It states its required headers, its request fields and validation rules, its success status and headers, and its full response body. It also states every named failure with a machine-readable body, whether a retry is safe, and what future additions old callers must tolerate.
That is a long list to invent under time pressure. It is a short list if most of it was settled before the interview began.
4. Predictability Is the Design Goal
One endpoint can be clear and still belong to a poor API.
GET /customers/cus_82M POST /create-invoice PATCH /subscriptions/sub_7KB POST /cancelSubscription
Each of those four may work. Together they have no grammar. Two paths are nouns and two contain actions, one action is camel case and the other is hyphenated, so nothing a caller learned from the first line helps with the fourth.
Replacing them with POST /invoices and DELETE /subscriptions/sub_7KB repairs the grammar. Whether deletion is the right way to express cancellation is a separate question. You can only debate that question once the surface is regular enough to compare.
Consistency covers more than URLs. A caller also learns your patterns for identifiers, timestamps, list envelopes, pagination, success statuses, error bodies, concurrency checks, rate-limit headers, and deprecation. If one list returns a bare array, a second returns results, and a third returns items, every operation has to be memorized separately. If every list returns items and next_cursor, one piece of client code serves the whole API.
Interview language "I will use REST as the default and establish one grammar for resources, URLs, methods, list responses, and errors. Once I choose a convention, I will reuse it, so a caller who has seen two operations can predict the third."
That sentence makes a scoring signal visible. You are not drawing isolated endpoints. You are designing one contract.
5. The Decisions This Chapter Makes Once
Each remaining lesson settles a question that otherwise invites a fresh invention in every interview.
The sequence matters. URLs are easier to design once the resources are known. Response bodies are easier once the operations are known. Pagination and filtering are easier once list shapes and field types are stable. The chapter works the way the interview method works: make one layer of the contract visible before adding the next.
Some conventions recur so often that later lessons and capstones apply them without reopening the decision.
These are not the only defensible choices, and another coherent API could settle several of them differently. They are the published language of this course, fixed so that every lesson demonstrates one contract rather than a collection of preferences.
Behave the same way in an interview. Choose a reasonable convention, state it, apply it everywhere, and spend the remaining minutes on the decisions that are specific to the product.
Key Takeaways
- Chapter 2 goes deep on Resources and Operations and supplies the conventions Step 4 needs to design one operation in full.
- The order is caller job, resource, one-line operation, complete contract, and it does not begin with the database.
- One resource and a fixed method vocabulary can carry several caller verbs, which is what makes the next operation predictable.
- An operation name holds two decisions; the gradeable ones are its inputs, output, success, failures, retry behavior, and change rules.
- Consistency lets a caller who has learned two operations predict the third, so choose each convention once and reuse it.
- The conventions here are fixed for the rest of the course, so later lessons demonstrate one contract instead of a set of preferences.
You now know what this chapter will build. The next lesson makes the first modeling decision: which nouns deserve to become resources, which belong inside another resource as fields, and where behavior that is not ordinary create, read, update, or delete should go.
On This Page
- The Direction Is Fixed
- What Steps 2 and 3 Produce
- An Operation Name Is Not Yet a Contract
- Predictability Is the Design Goal
- The Decisions This Chapter Makes Once
Key Takeaways