In the previous lesson, 06-01, we closed the technical write-up of the Aroma Store API with a list of certainties: offset pagination, exact counters, authorisation based on ownership of the resource, collections wrapped in data with their total, and real time as an accessory of the internal panel. All those decisions were right for that domain. Now we change domain without changing architectural style: we design CafeSocial, the tasters' network Aroma Store wants to launch, and one by one we are going to watch those certainties fall. Not because they were wrong, but because they were tied to a context that no longer exists. That contrast —the same REST discipline producing opposite designs— is the real content of this lesson.

1. The scenario: CafeSocial, requirements and consumers
2. Modelling the relationship graph with REST
3. The timeline: fan-out, derived resource and opaque cursor
4. Volume and scale: approximate counters, caching and queues
5. User-generated content: upload, moderation and reports
6. Privacy and resource-level authorisation
7. Notifications and real time
8. Aroma Store versus CafeSocial, decision by decision
9. Why GraphQL is defensible here
10. Common mistakes and tips
11. Exercises and solutions

CafeSocial is a vertical social network for coffee tasters. A user publishes a tasting: a photo of the coffee, the variety, the origin, the brewing method and a score from 0 to 100. Other users comment, give "likes", follow the tasters that interest them and receive a timeline with the posts of the people they follow. There are hashtags (#geisha, #v60), notifications and direct messages.

The identifiers keep the course's convention: usr_10, usr_77, pst_2100, cmt_310, ntf_55. The JSON is still camelCase, the errors still follow the {"error": {"code","message","details":[]}} catalogue and the version is still in the path (/v1). The domain changes, the conventions do not: that is precisely what makes comparison possible.

• Mobile app (iOS/Android): the main consumer, with limited bandwidth and battery. Every byte and every round trip hurts.
• Public web: profiles and posts indexable by search engines when they are public.
• Internal moderation panel: few users, broad permissions, needs work queues.
• Integration with Aroma Store: when a post mentions a coffee from the catalogue, the card links to /v1/coffees/cof_001 of the store's API. They are two separate APIs linked by hypermedia, not one.

Unlike the store, here there is no money in the request. Nothing demands the transactional exactness that in 06-01 forced us to solve overselling inside the UPDATE. That freedom is what makes almost everything that follows possible.

At Aroma Store almost everything was a simple containment relationship: an order belongs to a customer, an item belongs to an order. Here the relationship is the interesting entity.

They are two views of the same edge, from its two ends. Neither is "the right one": the app needs both, and with very different cardinalities (a user follows 300 people but may have 300,000 followers).

The temptation is to invent a verb: POST /v1/follow with {"followedId": "usr_77"}. It works, and it is exactly what in 02-02 we called turning an action into a resource without need. The alternative is to treat the edge as an addressable resource:

The advantages, going back to the methods table of 02-03:

In a mobile app on an unstable network, idempotency is not theoretical elegance: it is the difference between a button that gets stuck halfway and one that does not. The client can retry the PUT without thinking.

GET /v1/users/usr_10/following/usr_77 returns 204 if the relationship exists and 404 if it does not, which gives the client a cheap check for rendering the button.

Both forms are legitimate and it is worth understanding the trade-off:

At CafeSocial we chose A for the follow graph and for "likes", for consistency and because the moderation panel needs to be able to remove another user's "like". The rule we applied: if any legitimate consumer can act on a third party's relationship, the subject goes in the path. When the path and the token do not match and the caller lacks the appropriate scope, we respond 403 with insufficient_permissions.

An edge with attributes stops being a simple "it exists or it does not". Following someone can carry preferences:

A practical rule: with no attributes, 204 and an empty body; with attributes, 200 and a full representation with an ETag, and then partial modifications (PATCH) and the optimistic concurrency of 03-06 apply again. Do not invent attributes "just in case": an edge with a body costs one wider row multiplied by 180 million.

When usr_77 posts, who pays the cost of it appearing in their followers' timelines?

With 500 reads for every write, fan-out on write wins almost every time. The problem is the long tail: if usr_77 is a famous taster with a million followers, every post fires a million inserts and the queue backs up for minutes.

A hybrid solution, which is the one CafeSocial adopts:

1. Users with fewer than 10,000 followers use push: when they post, an asynchronous task inserts the reference into every follower's inbox.
2. Users above that threshold are marked as reach accounts and use pull: they distribute nothing.
3. GET /v1/timeline reads the user's inbox and merges on the fly the recent posts of the few reach accounts they follow (usually fewer than 20), ordering by timestamp.

It is more code and more complexity, but it is the only design that survives both ends of the distribution.

At Aroma Store, /coffees was a collection: you could create (POST), count (total), filter and jump to page 7. The timeline is none of that: it is a derived resource, a computed view that only exists for one user and at one instant.

Put another way: /timeline answers "what is new for me?", not "what elements does this set contain?". Just as in 02-06 we distinguished search from listing, here we distinguish a feed from a collection.

Recall the mechanism from 02-06: ?limit=20&offset=20 translates to LIMIT 20 OFFSET 20. That assumes the ordered set does not change between requests. In a timeline ordered by date descending, it changes every second.

A worked example. usr_10's timeline contains, ordered newest to oldest, the posts pst_2100 (position 1) down to pst_2001 (position 100).

The duplicates case. The client asks for the first page:

While the user is reading, 3 new posts arrive. Everything has now shifted by 3 positions. The client asks for the second page:

pst_2084, pst_2083 and pst_2082 had already been shown on the first page. The user sees three repeated posts.

The gaps case. With the same initial state, between the first and the second request 3 posts are deleted from among the first 20. When offset=20 is requested, positions 21..40 of the reduced set correspond to what used to be positions 24..43: pst_2078 and the two before it are never shown. The user will never see them, and there is no visible error to give it away.

Add to that the fact that OFFSET 200000 forces the engine to walk and discard 200,000 rows: the cost grows with depth. Duplicates, silent gaps and growing cost: three independent reasons, each one sufficient on its own.

At Aroma Store the cursor was an option we applied to /orders. Here it is mandatory. The cursor implements keyset pagination: instead of "skip 20 rows", it says "give me what comes before this exact point".

Contents of the cursor: timestamp + tie-breaking id. The timestamp alone is not enough because two posts can share a millisecond; the id breaks the tie and guarantees a total ordering.

The corresponding query uses tuple comparison, which takes advantage of the composite index (user_id, created_at DESC, post_id DESC):

The response carries no total —there is none— and exposes the next link both in the body and in the RFC 8288 Link header, just as in the store:

Why opaque. The cursor is base64url of a JSON object, not encrypted: anybody can read it. Opacity is a contract, not a security measure: by not documenting its innards, tomorrow we can move from (date, id) to a position identifier in a distributed index without breaking any client. What we do guarantee is validation: if the client tampers with it, decoding fails (400 invalid_cursor) or the values do not pass the type check. And because the cursor does not contain the user's identifier —that always comes from the token— tampering with it does not let you read someone else's inbox. That point is essential: never put authorisation information inside a cursor.

Maximum age. Inboxes are trimmed to the last 800 entries and to 30 days. An older cursor points at nothing, so we respond 410 Gone with expired_cursor and the client goes back to the beginning, instead of returning an empty list that the app would read as "end of content".

At Aroma Store, stock had to be exact: that is where the condition inside the UPDATE that solved overselling came from. Here, SELECT COUNT(*) FROM likes WHERE post_id = 'pst_2100' on every read of the timeline means 20 counting queries per screen, multiplied by millions of screens.

The decision: a denormalised counter, updated asynchronously and declared as approximate.

The consequences have to be accepted explicitly, not hidden away:

• The response sets "approximateLikes": true when the counter goes above 1,000. Below that it is recomputed on the fly and is exact: users notice a discrepancy in 12 but not in 12,480.
• A nightly job reconciles the counters against the real table.
• The user always sees their own "like" reflected immediately (read-your-own-writes), even if the global number lags behind: that is what stops the interface looking broken.

Picking up 04-06, the profile is the ideal candidate for caching: it is read constantly and changes little.

The delicate part is what can be cached in a shared way:

Vary: Authorization is correct but, in practice, it destroys the shared cache: every token produces a different entry. That is why the real strategy is to split the response in two: the objective profile data (handle, biography, photo) is served cacheable and public, and whatever depends on the observer (followingThisUser, hasBlockedMe) is requested separately or marked private. Caching the mixture is the classic mistake, and its most serious version is a proxy handing the profile "as seen by another user" to somebody who should not have it.

Fan-out distribution and other long operations do not fit inside the request cycle. Just as in 04-06 with the store's reports:

Posting is the same thing in reverse: POST /v1/posts responds 201 immediately with the created post —the author already sees it on their profile— while the distribution to the inboxes happens behind the scenes. It is eventual consistency turned into a contract: a follower may take a few seconds to see it, and that is documented.

Denormalising is not free. At CafeSocial we pay for it: multiplied storage (a post appears in hundreds of thousands of inboxes), a more fragile write path (if the queue fails, there are incomplete inboxes and a repair process is needed), and two sources of truth that can diverge. The rule is that the canonical source is still /posts/{id}; the inboxes are a rebuildable cache. Anything that can be regenerated from the canonical source is acceptable to denormalise; anything that cannot, is not.

The API does not receive the megabytes of the photo. An authorisation is issued for uploading directly to object storage:

The reasons for not passing the bytes through the API are concrete:

• A Node process tied up for 8 seconds with a 5 MB upload is a process that is serving nobody else.
• Scaling the upload traffic is decoupled from scaling the business logic.
• Storage and the CDN already solve resumption, multipart uploads and geographical distribution.
• Proxy and load-balancer timeouts stop being a problem.

Validation. The pre-signed URL limits type and size, but that is not enough: the client declares image/jpeg and uploads whatever it likes. That is why confirmation is mandatory and checks the real bytes on the server (magic numbers in the file header, dimensions, size), reprocesses the image into several sizes and strips the EXIF metadata —which includes GPS coordinates: publishing the exact location of a user's home would be a personal data leak. An image left unconfirmed for 15 minutes is deleted and the post stays a draft.

The status mirrors that of the Aroma Store reviews: pending_moderation | published | rejected. What changes is the scale, which forces two stages:

1. Automatic, immediately: an image and text classifier. Low score, published straight away; medium score, human queue; high score, immediate rejection with the possibility of appeal.
2. Human, over a work queue:

Design details that matter:

• The moderation queue lives under /moderation/*, a namespace of its own with its own scopes (moderation:read, moderation:write). Mixing it into /posts would force the same endpoint to behave radically differently depending on the scope, which is exactly what makes tests ungovernable.
• Approval and rejection are action resources (POST to a sub-resource) because they are not idempotent in their effects: they fire notifications and they are audited. Every decision is stored with the moderator, a timestamp and a reason.
• The queue is paginated by cursor: it grows and is consumed at the same time.

We respond 202 and not 201 with a verdict: the report is accepted, not resolved. The reporter must not be able to see the detailed status or the moderator's identity, and the reported user must not learn who reported them. Several reports about the same post are aggregated into a single case.

An essential warning. Everything above is the engineering part, which is the easy part. A real service with user content has legal obligations that are not technical decisions: lawful bases and GDPR rights, deadlines for taking down illegal content, protection of minors and age verification, data retention and disclosure to authorities, moderation transparency and routes of appeal. They vary by country and over time. Design it with legal and compliance advice from the start; a deletion endpoint that misses the legal deadline is a legal problem, not a TODO in the backlog.

At Aroma Store the question was "who owns this?": order ord_5001 belongs to cus_842, so only cus_842 and the administrators see it. Binary and simple.

At CafeSocial the question is "who is asking and what do we let them see?", and the answer is no longer yes or no, but a different representation:

The pattern: the service layer returns the full entity and a projection decides which fields survive, according to the relationship between observer and observed.

Three rules that avoid the usual failures:

1. An allowlist, never a blocklist. A new field on the entity must not leak just because it has been added.
2. The projection applies inside lists too. GET /users/usr_77/followers trims out blocked and private users: the list returned may be shorter than the counter shown on the profile, and that is correct.
3. Visibility is decided in the query, not afterwards. Filtering in memory after fetching 50 rows breaks cursor pagination: you would ask for 20 and return 14.

If usr_77 blocks usr_10 and the latter requests GET /v1/users/usr_77, a 403 insufficient_permissions would be technically honest and it would leak information: it would confirm that the account exists, and by the difference between responses you could enumerate who has blocked whom or discover which handles are registered. When the mere existence of the resource is sensitive information, you respond 404.

The general criterion: 403 when the resource is known to the caller or its existence reveals nothing (the moderator without the right scope); 404 when revealing the existence is itself a leak. And you have to be consistent in response times: a 404 that takes 5 ms when the resource does not exist and 40 ms when it exists but is blocked leaks the information again through a side channel.

• Caching: any response whose shape depends on the observer is private and carries Vary: Authorization. A shared CDN can only serve what is objectively public. This reduces performance and it is a cost accepted consciously.
• Tests: the matrix grows all at once. Every sensitive endpoint needs cases for owner, follower, non-follower, blocked and anonymous. At CafeSocial it is handled with a parameterised table of cases:

At Aroma Store, SSE was an extra for the internal panel. Here, immediacy is the product: a social network where the notification arrives two minutes late is perceived as broken.

Pure REST would force polling: the app asks GET /v1/notifications every 10 seconds. With 500,000 active users that is 50,000 requests per second, 99 % of which return the same thing. Not even with ETag and 304 (which save bandwidth, not requests) do the numbers add up.

The design combines three pieces:

The history is paginated by cursor (the same mechanism as the timeline) and the live channel only carries notices that there is something new, not the full content: the client receives the signal and reloads over REST. That way the real-time channel does not turn into a second API to maintain in parallel.

CafeSocial uses SSE for the web and the notification counter, WebSockets only on the direct messages screen, push when the app is not active and webhooks signed with HMAC-SHA256 towards Aroma Store, reusing exactly the mechanism from 06-01.

This is the table that makes sense of the two lessons together.

The conclusion is not that one design is better. It is that there is no universal REST design: there are domain-dependent decisions, and professional competence consists in knowing which one applies and being able to justify it. If somebody offers you "the right way to paginate" without asking about the domain, they are selling you an answer before they have heard the question.

In 01-07 we concluded that for Aroma Store GraphQL would have been complexity with no return: few screen types, high value from HTTP caching on the catalogue, one very stable main consumer. At CafeSocial the arguments flip sign:

• Screens with heterogeneous data. The detail view of a post needs the post, the author, whether I follow them, the first five comments with their authors, the "like" counter, whether I liked it, the hashtags and the linked catalogue coffee. In REST that is 5-7 requests, or a bespoke composite endpoint that ages badly.
• Mobile clients with limited bandwidth. The list needs 6 fields per post; the detail view, 30. With REST you end up inventing ?fields= or ?view=summary, which is GraphQL done badly.
• Fast client evolution. A redesign of the timeline every quarter means, in REST, negotiating contract changes with the backend every quarter.
• A graph is queried like a graph. "The latest comments from the people I follow on posts that my followers also liked" is a natural query in GraphQL and a contorted endpoint in REST.

And what you lose, which has to go on the same scales:

The realistic decision at CafeSocial —and the one you will see in many companies— is hybrid: GraphQL for the mobile app's screens, REST for what is public and indexable (profiles and posts cacheable in a CDN), for third-party integrations and for webhooks. Choosing GraphQL is not abandoning what you have learned: the resources, the states, idempotency, cursor pagination and observer-based authorisation remain exactly the same problems; only the transport layer changes.

1. Using POST /follow because "it is an action". You lose idempotency, and querying and deleting for free. If the action creates or destroys a relationship between two identifiable entities, that relationship has a URI: PUT/DELETE (02-03).
2. Putting authorisation information inside the cursor. A cursor with a userId inside is a privilege escalation waiting to happen. The subject always comes from the token.
3. Confusing opaque with secure. Base64url encrypts nothing. Opacity is freedom to change the format, not protection: always validate the decoded content.
4. Returning a total on a feed. It forces an expensive COUNT over a set that changes, and the resulting number is false the moment it is sent. Use hasMore.
5. Filtering by visibility after paginating. You ask for 20, hide 6 and return 14: the client thinks it is reaching the end. Visibility goes in the query.
6. A blocklist of fields in the projections. The day you add recoveryEmail to the entity, it will publish itself. Always an allowlist.
7. 403 where existence already leaks information. And watch out for response times and error messages too, which leak through side channels.
8. Caching as public a response that depends on the observer. It is the fastest route to a proxy serving one user's private profile to another. When in doubt, private.
9. Uploading large files through the API. It ties up processes, collides with proxy timeouts and does not scale. Pre-signed URL and later confirmation.
10. Trusting the Content-Type declared by the client. Verify the real bytes, reprocess the image and strip the EXIF metadata before publishing it.
11. Designing fan-out with a single algorithm. Pure push dies with heavily followed accounts; pure pull dies on latency. The hybrid is ugly and it is the one that works.
12. A process tip: write the comparison table from section 8 before you start coding. It forces you to justify every decision against a concrete alternative and it is the best defence against copying the last project's design out of inertia.

Exercise 1 — The graph as a resource. Design the endpoints for "muting" a user you follow (you stop seeing their posts in your timeline, but you remain their follower). State the method, the URI, the status codes and whether it needs a body. Justify why you would not model it as POST /v1/mute.

Exercise 2 — A tamper-proof cursor. A client sends ?cursor=eyJ2IjoidjEiLCJ0IjoiMjAzMC0wMS0wMVQwMDowMDowMFoiLCJpIjoicHN0Xzk5OTk5In0 (a date in the future). Explain what the system returns, why that is not a security flaw, and add the missing validation to decodeCursor.

Exercise 3 — Projection and pagination together. GET /v1/users/usr_77/followers?limit=20 must hide the users who have blocked the observer. Explain why filtering in memory breaks pagination and sketch the correct SQL query with a cursor.

Solution 1. Muting is an attribute of an existing relationship, not a new relationship:

Codes: 200 on success; 404 if you do not follow that user (there is no relationship to modify); 412 if the If-Match does not match; 422/400 with invalid_data if the body does not validate. POST /v1/mute is not used because the relationship already has a URI: creating a parallel verb would duplicate the resource, lose the idempotency of a PATCH against a specific state and force you to invent POST /v1/unmute. An equally valid alternative: a PUT over the complete relationship with all its attributes, if you prefer to avoid PATCH.

Solution 2. The system decodes the JSON correctly (a valid v, t and i present), the age check does not trigger because the date is in the future, and the query WHERE (created_at, id) < ('2030-01-01', 'pst_99999') simply returns the first page, since everything is earlier than that date. It is not a security flaw because the userId in the WHERE comes from the token, not from the cursor: tampering with it only lets you reposition yourself within your own inbox, something the user can already do by paginating. Even so, it is worth rejecting it in order to detect broken clients:

Solution 3. Filtering in memory breaks pagination because the LIMIT is applied before the filter: you ask for 20 rows, discard the 6 belonging to users who have blocked you and return 14, while the cursor advances as if you had delivered 20. The client sees irregular pages and, if a whole page comes out empty, reads it as the content having run out. The filter has to go in the query:

A consequence that has to be documented: the number of items walked may not match the profile's followers counter, because that counter is global and the list is relative to the observer. And because the response depends on the observer, it is private with Vary: Authorization.

We have designed CafeSocial with the same tools as Aroma Store —resources, methods, status codes, headers, hypermedia— and we have ended up with an almost opposite design. The follow relationship stopped being a field and became a resource with an idempotent PUT and a DELETE. The timeline stopped being a collection and became a derived resource with no POST, no total and no page N, held up by a hybrid fan-out and reachable only through an opaque cursor of timestamp plus id. The counters stopped being exact because counting stopped being worth it. The images left the API. Authorisation stopped asking who owns the resource and started asking who is observing, with projections by visibility and 404 wherever existence is itself information. And real time stopped being an ornament and became the product.

If this lesson leaves one single idea, let it be the one in the table in section 8: there is no universal REST design, there are domain-dependent decisions, and a professional is distinguished by being able to name the alternative they rejected and why. That is also the reason GraphQL, indefensible for the store's catalogue, is a serious option here, as long as the price is accepted: losing HTTP caching, status codes and control over the cost of queries.

One last matter remains, and it is the one that separates a well-designed API from an API that is still alive three years later: what happens after you publish it. In 06-03, Evolving and Maintaining an API in Production, we will look at what to do when an apparently harmless change breaks a consumer in production, how to write a post-mortem that is actually useful, how contract debt is accumulated and paid off, and how a migration to v2 is planned with its deprecation period and its governance. Because designing an API well is hard, but changing it without breaking whoever already uses it is harder still.