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 listed these operations:
POST /v1/links GET /v1/links/{link_id} GET /v1/links?cursor=...&limit=... DELETE /v1/links/{link_id} GET /v1/links/{link_id}/statistics
Each line contains design choices. This chapter explains them in more detail.
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 introduced REST. This chapter explains the reasons for these choices and establishes conventions you can reuse in later examples.
1. The Direction Is Fixed
The six-step method stays the same. Chapter 2 focuses on Resources and Operations, then provides the details needed to define one complete operation in Step 4.
The other steps remain important. Step 1 identifies client tasks. Steps 5 and 6 address difficult behavior and the disadvantages of the chosen design.
Inside those two middle steps, the order of the decisions matters most.
Start with a client task, identify the resources it needs, list the operations, and define their behavior. Do not begin by turning database tables into endpoints.
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.
The next lesson explains which concepts should become resources. Choose them based on client needs rather than database names.
2. What Steps 2 and 3 Produce
Step 1 identifies client tasks. Steps 2 and 3 turn them into resources and operations.
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.
These four tasks can use a shared resource model rather than four separately named action endpoints.
A SavedArticle supports these tasks. It has an opaque id, the original url, a display title, a status, and timestamps such as created_at. In this example, authentication identifies the reader, and each operation checks ownership. The reader's saved articles form a collection, so a separate reading-list resource is unnecessary for this scope.
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
In Step 3, list one line per operation to establish the scope. In Step 4, define the most important operation in detail.
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.
Practice these details before the interview so that you can apply them within the available time.
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 operation may work, but their naming patterns differ. Two paths name resources and two name actions. The action names also use different casing. These differences make related operations harder to predict.
Using POST /invoices makes creation consistent with the resource-oriented paths. For cancellation, first decide the intended behavior: it might update subscription state or create a cancellation record. Do not choose DELETE just to make the URL pattern look consistent.
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."
This statement shows that the operations follow a shared set of rules.
5. The Decisions This Chapter Makes Once
Each remaining lesson explains a different set of contract decisions.
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 course conventions, not universal requirements. Other APIs can make different choices and still be consistent. Follow the stated defaults unless a lesson explains a product-specific exception.
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; a complete answer also defines inputs, outputs, success, failures, retries, 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.
Reading Progress
0%
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