Resource Modeling

## Definitions first A **resource** is the target of a URI: any information worth naming — a document, a collection, a computed value, a real-world object, a process. Its **representation** is the bytes you send for it (a JSON document, a PDF, an image); one resource can have several representations. An **entity** in the domain sense is an object with identity that persists over time — a Customer, an Order. A **table** is a storage artifact. The common beginner move is `table → resource`, one for one, CRUD on each. It works for simple systems and quietly fails as the domain grows, because storage is optimised for writes and normalisation while an API is optimised for the interactions clients actually have. ## Where the mappings diverge **One entity → many resources.** Split when parts of an entity differ in *permission*, *volatility*, or *size*. - Permission: `/users/{id}` (self and admins) versus `/users/{id}/public-profile` (anyone). - Volatility: a product's description changes monthly and its price and stock change every minute. One resource means you either cache aggressively and serve stale prices, or cache nothing and pay for the description every time. Two resources give two cache lifetimes. - Size: an article's body versus its comments; separate resources let each paginate and cache on its own. **Many entities → one resource.** A checkout page's data may come from cart, pricing, promotions and inventory. Exposing four resources forces every client into four round trips and re-implementing the join. A single `/checkouts/{id}` that composes them is a legitimate resource — the API's job is to serve the interaction, not to publish the schema. **Resources with no entity.** Computed or derived things are first-class resources: `/reports/monthly-revenue?month=2026-07`, `/accounts/{id}/balance`, `/orders/{id}/invoice` in `application/pdf`. They have URIs, representations, cache semantics and ETags like anything else. **Processes as resources.** Operations that take time are best modelled as a resource representing the operation: `POST /exports` returns `202 Accepted` with `Location: /exports/{id}`, and `GET /exports/{id}` reports `status: running|done|failed` with a link to the result. This turns "a thing happening" into something addressable, pollable, cancellable and auditable. **Entities with no resource.** Join rows, audit tables, internal caches. Exposing them leaks the schema and creates a contract you must maintain. Publish what clients need. ## Document versus collection versus controller resources A useful vocabulary: - **Document** — a single thing: `/orders/42`. - **Collection** — a server-managed set of documents: `/orders`. - **Store** — a client-managed set where the client picks the key: `PUT /users/7/bookmarks/{clientKey}`. - **Controller** — a resource representing an executable concept when no document/collection mapping is honest. Recognising which kind you are creating keeps the verbs consistent: collections take `POST` to create and `GET` to list; documents take `GET`/`PUT`/`PATCH`/`DELETE`; stores take client-keyed `PUT`. ## Granularity signals in practice Split a resource when: parts have different permissions; parts have very different change rates; part of it is unbounded (a growing list) and would make the parent's representation grow without limit; clients routinely want one part without the other; or two parts need independent optimistic-concurrency control, because a single ETag over a whole aggregate makes unrelated edits collide. Merge when: clients always fetch the pieces together; the pieces change together and share a lifecycle; or splitting would force clients to reassemble an invariant the server should own (never make a client responsible for keeping two resources consistent — if updating them together must be atomic, they are one resource). ## A worked example A `Subscription` entity in the database has plan, price, status, card token, billing address, and a usage counter. As an API: - `/subscriptions/{id}` — plan, status, dates. Moderately cacheable, owner-readable. - `/subscriptions/{id}/payment-method` — separate permission, separate audit, PCI-sensitive, changed by a different flow. - `/subscriptions/{id}/usage` — high-volatility counter, short cache, cheap to fetch alone. - `/subscriptions/{id}/invoices` — an unbounded collection, paginated, would otherwise inflate the parent forever. One table, four resources — each with its own cache policy, permission and concurrency token. That is the mapping doing real work rather than mirroring storage.