CodePark/ questions / REST resource design
START PRACTICINGPRACTICE
Backend question · HTTP & API design › REST resource design

What are the core principles of REST?

REST is an architectural style defined by a set of constraints (rules). Roy Fielding described it.

The constraints:

  • Client-server: the UI is separate from data storage.
  • Stateless: each request contains everything needed to handle it. The server keeps no client session between requests.
  • Cacheable: responses say whether they can be cached.
  • Layered system: clients cannot tell if they talk to the origin server or to a proxy or CDN.
  • Uniform interface: URLs identify resources. Clients change resources through representations like JSON. Messages describe themselves. Hypermedia links tell the client what it can do next. This last part is called HATEOAS.
  • Code on demand: the server may send code to run on the client. This one is optional.

In day-to-day API design, this means:

  • model resources as nouns
  • use HTTP methods for actions
  • use status codes for outcomes
  • use headers for caching and content negotiation

Most real-world JSON APIs skip HATEOAS.

  • REST separates client and server, and requests are stateless.
  • Responses are cacheable, and the system can have layers like proxies and CDNs.
  • The uniform interface means resources, representations, self-descriptive messages and HATEOAS.
  • In practice, use nouns for resources, HTTP methods for actions and status codes for outcomes.