Glosarium
Contents

Web & Networking › API Styles & Formats

Resource Modeling

Deciding what your API's resources are and how they relate.

Backend Engineer · Mid-levelFrontend Engineer · Mid-levelData Engineer · Mid-level

Also known as: resource modeling, resource modelling, rest resources

Resource modeling designs an API as addressable nouns — collections and members with stable URLs — manipulated through HTTP methods, rather than as remote procedure names. /orders/42 and /orders/42/items instead of /getOrderItems?orderId=42.

GET    /orders            collection
POST   /orders            create member
GET    /orders/42         member
GET    /orders/42/items   sub-collection
POST   /orders/42/cancel  action (the honest exception)

Good models expose hierarchy where it exists (sub-resources), keep URLs stable and guessable, and reserve verb-style endpoints for genuine actions that aren’t CRUD (cancel, approve, publish). The URL structure becomes navigable documentation.

The classic mistakes:

  • Verbs everywhere. /createOrder, /deleteUser?x=1 discards methods, caching and idempotency semantics. Nouns with methods; verbs only for true actions.
  • Deep nesting. /a/1/b/2/c/3/d couples clients to the whole chain and complicates auth. Nest one level where ownership is real; reference by id beyond that.
  • Inconsistent pluralisation and casing. Mixing /Order, /orders, /order-items and /orderItems makes the API feel generated by accident. Pick naming conventions and lint them.
  • Exposing database ids as the model. Surrogate keys in URLs are fine, but the resource is the domain concept — model relationships users understand, not tables.
  • Actions disguised as resources. A “resource” that’s really an RPC call (POST /calculate) confuses caching and semantics. Name actions honestly under their parent.
  • No collection discipline. Pagination, filtering and sorting should work uniformly across collections — designed once, applied everywhere.
  • Leaking hierarchy into authz gaps. Nested URLs tempt path-based permission checks that miss direct member access. Authorise the resource, not the URL shape.

How to model: nouns for things, methods for operations, one nesting level for owned children, actions as clearly-marked exceptions, uniform collection behaviour. The URL tree should read like the domain, not the database.