fundamentals
Resource Modeling
Find the right granularity for resources — neither so fine that clients make 50 calls, nor so coarse that updates are clumsy.
Resource modelling is the design work of deciding what your API's nouns are, how they relate, and at what granularity to expose them. Get it wrong in one direction and resources are so fine-grained that rendering a single screen takes fifty round trips; wrong in the other and they are so coarse that every small update means sending and re-validating a huge object. Good resource modelling finds the granularity that matches how clients actually use the data.
A menu with combo meals (the common order) but also à la carte items (when you need just one piece).
Key Concepts
1
The conventions that make an API feel natural are largely about consistency. Resources are named with plural nouns (/orders, /users), with the collection at /orders and an individual member at /orders/{id}. Relationships are expressed through nesting where there is genuine containment — /orders/{id}/items for the line items belonging to an order — while independent entities get top-level URLs and are linked by id. Actions that do not fit a verb (cancel an order, send a reminder) are usually modelled as sub-resources or state transitions rather than RPC-style verbs in the path. Filtering, sorting, and pagination ride on query parameters (/orders?status=open&sort=-createdAt) rather than spawning new paths. The aim is that a developer can guess the URL for a resource they have not seen yet.
/orders/users/orders/{id}/orders/{id}/items/orders?status=open&sort=-createdAt
2
The judgement interviewers look for is balancing call granularity against payload size and update clarity: nest only one or two levels deep before relationships become unwieldy, avoid deeply nested URLs that couple unrelated lifecycles, and consider sparse fieldsets or an aggregate/BFF endpoint when a client genuinely needs many related resources at once. The recurring theme is to model resources around the consumer's real workflows, keep naming consistent and predictable, and resist both the chattiness of over-decomposition and the bloat of god-objects.