DesignFlix 6: REST Is More Than URLs and JSON

A URL, a GET request and some JSON: is that enough to make an API RESTful?

It's a familiar starting point, but REST describes more than that format. Its constraints shape how clients and servers communicate, how responses can be reused, and how intermediaries can sit between them.

Let's use a small library API to make those ideas concrete. We'll follow a book request rather than memorise six names and hope the architecture follows.

Let the client and server own different work

The library interface displays books and lets readers request a loan. The server owns catalogue data and validates whether a loan may be created.

That client-server separation lets a mobile app and website use the same service contract. They can have different layouts without duplicating the loan rules in both interfaces.

Independence still depends on preserving the contract. Changing a response or rule incompatibly can break a client, even when its code lives in a different repository. Separation gives us a boundary to manage, not a guarantee that changes never affect the other side.

Give every request enough context

Suppose the client requests book 17. In the stateless interaction model, the request includes the context needed to process it without relying on a hidden conversation established by earlier calls.

An illustrative request is:

GET /books/17 HTTP/1.1
Host: library.example
Accept: application/json

If the operation needs credentials, include them through the API's supported authentication mechanism. Don't require the server to remember that the preceding request selected a branch or changed the caller's interaction mode.

Stateless doesn't mean the server stores no data. The catalogue, accounts and loan records still exist. The distinction is between resource state and conversational client context that must be carried from one request to the next.

Cool. Stateless. No doubt.

A uniform interface includes more than tidy URLs

REST's uniform-interface constraint has four parts: identifying resources, manipulating them through representations, self-descriptive messages, and hypermedia guiding the available interactions. Roy Fielding's original REST chapter describes these together.

For the library, /books/17 identifies a resource. Its JSON response is a representation of the book, not the database row itself. Different formats could represent that resource without changing its identity.

An illustrative representation might include links:

{
  "id": 17,
  "title": "The Guide",
  "links": {
    "self": "/books/17",
    "loans": "/books/17/loans"
  }
}

Under an agreed media format, those links help the client discover relevant interactions. Their presence doesn't mean anyone may create a loan; authorization and availability still apply.

HTTP methods, statuses and headers help describe the exchange. GET retrieves a representation, while POST can submit a supported operation such as creating a loan. The exact contract matters more than calling every route "REST" because it uses JSON.

Say when a response can be reused

A public book description changes infrequently. A response can advertise a freshness period, allowing suitable caches to reuse it without contacting the server for every view.

A current loan balance or personalized account response has different requirements. Use cache rules that fit both freshness and access. private limits shared caching; no-store asks caches not to store the response. These aren't interchangeable statements; the HTTP caching standard defines their separate effects.

Caching is part of the response contract. Ask how an edited description becomes visible and whether an old availability value could mislead a reader. A cached book page shouldn't be treated as final permission to borrow the last copy.

Layers let the path change behind the interface

The request may pass through a CDN, gateway or proxy before reaching the library service. The client talks to its configured endpoint without having to know every internal component.

Those layers can provide routing, security controls or caching, but they also have to preserve the interface's meaning. A proxy that retries an unsafe change or caches a private response can break the feature despite forwarding valid HTTP.

The layered-system constraint makes intermediaries possible. Understanding their behaviour remains part of operating the API.

Code on demand is optional

A server can supply executable code that extends client behaviour, such as JavaScript. REST includes this as an optional constraint.

A JSON API doesn't need to send code just to satisfy a checklist. Include it when the client arrangement benefits from it and the execution model is appropriate. It isn't the missing ingredient that automatically makes every HTTP API RESTful.

Apply the ideas to one working exchange

Can another developer tell what this request means without knowing the calls that happened before it?

Start there, then inspect the resource identity, representation, methods, links and cache policy. Test the same request from another client and through an intermediary.

REST gives us a set of architectural constraints for those interactions. Many practical HTTP APIs adopt only parts of that style. Be clear about what your API implements, and use the constraints to improve its behaviour rather than treating the label as a substitute for a usable contract.