REST - Should an API client "advance" to the "next" resource like a browser?

Question

In my years specifying and designing REST APIs, I'm increasingly finding that its very similar to designing a website where the user's journey and the actions and links are story-boarded and critical to the UX.

With my API designs currently, I return links in items and at the bottom of resources. They perform actions, mutate state or bring back other resources.

But its as if each link opens in a new tab; the client explores down a new route and their next options may narrow as they go.

If this were a website, it wouldn't necessarily be a good design. The user would have to either open links in new tabs or back-up the stack all the time to get things done.

Good sites are forward only, or indeed have a way to indicate a branch off the main flow, i.e. links automatically opening in new windows (via anchor tag target).

So should a good REST API be designed as if the client discards the current resource and advances to the next and is always advancing forward?

Or do we assume the client is building a map as it goes, like um a Roomba exploring our living room?

The thing with the map concept is that the knowledge that one should return to a previous resource, of the many it might know about, is in a sentient human, a guess. Computers are incapable of guessing and so its need programming, and this implies out-of-band static documentation and breaks REST.

Answer 1

In my years specifying and designing REST APIs, I'm increasingly finding that its very similar to designing a website

Yes - a good REST API looks a lot like a machine readable web site.

So should a good REST API be designed as if the client discards the current resource and advances to the next and is always advancing forward?

Sort of - the client is permitted to cache representations; so if you present a link, the client may "follow" the link to the cached representation rather than using the server.

That also means that the client may, at its discretion, "hit the back button" to go off and do something else (for example, if the link that it was hoping to find isn't present, it might try to achieve its goal another way). This is part of the motivation for the "stateless" constraint; the server doesn't have to pretend to know the client's currently displayed page to interpret a message.

Computers are incapable of guessing and so its need programming, and this implies out-of-band static documentation and breaks REST.

Fielding, writing in 2008

Of course the client has prior knowledge. Every protocol, every media type definition, every URI scheme, and every link relationship type constitutes prior knowledge that the client must know (or learn) in order to make use of that knowledge. REST doesn’t eliminate the need for a clue. What REST does is concentrate that need for prior knowledge into readily standardizable forms. That is the essential distinction between data-oriented and control-oriented integration.

Answer 2

I found this nugget in Fielding's original work.

https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations. Not surprisingly, this exactly matches the user interface of a hypermedia browser. However, the style does not assume that all applications are browsers. In fact, the application details are hidden from the server by the generic connector interface, and thus a user agent could equally be an automated robot performing information retrieval for an indexing service, a personal agent looking for data that matches certain criteria, or a maintenance spider busy patrolling the information for broken references or modified content [39].

It reads like a great REST application would be built to be forward only, like a great website should be simple to use even without a back button, including advancing to a previously-seen representation (home and search links always available).

Interestingly we tend to really think about user journeys in web design, and the term journey is a common part of our developer language, but in API design this hasn't yet permeated.