
REST APIs must be hypertext-driven (2008) - dvaun
https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
======
dozzman
Most of the APIs I use and build are best suited as RPC systems rather than
hypermedia networks, so implementing the entire REST idea has never been
immediately useful. Broadly the real consumers of RESTful APIs are not generic
hypermedia clients (generalisation of browsers) which are able to traverse
your flavour of hypermedia, but the things operating those clients. Most of
the time, those “things” are dumb business logic applications that can’t
explore the hypermedia to discover new functionality and furthermore are not
designed to do anything with it anyway.

If it is a human traversing the hypermedia however, they’re able to derive a
lot of understanding about the API and its features, as if the API is self
documenting, but that generally only occurs during the development and
debugging stages. After that the hypermedia is useless to the dumb business
logic. Also I’m sure most humans prefer to browse the documentation on the
alternative World Wide Web hypermedia network, as any good API would have
documentation published there.

All in all hypermedia is mostly useful for intelligent consumers, so if that
is not the consumer of your API and you suspect instead the consumer will be
static business logic (the vast majority of cases) then REST will not be
particularly useful. As I mentioned an interesting use case would be bundling
up documentation into the API itself and hyperlinking between that and related
URLs, however the overhead is generally not worth it since you’re likely to do
it better with documentation site.

~~~
rumanator
> Most of the time, those “things” are dumb business logic applications that
> can’t explore the hypermedia to discover new functionality and furthermore
> are not designed to do anything with it anyway.

Dumb business logic is not the point. One of the benefits of HATEOAS is that
it allows REST clients to be loosely coupled with REST services, in a way that
APIs can change freely change (i.e., change endpoints around, break away
functionalities into other services, etc.) without requiring clients to be
updated under the penalty of breaking compatibility.

The main reason why no one does REST and everyone does RPC-over-HTTP is that
while REST clients require tracking and updating state to support service
discovery, RPC-over-HTTP just requires a single HTTP request to achieve the
same purpose, albeit without the resilience and future-proof.

~~~
dozzman
> One of the benefits of HATEOAS is that it allows REST clients to be loosely
> coupled with REST services, in a way that APIs can change freely change

My point is that even though they're loosely coupled, the API actually cannot
change freely because the actual consumer of the API, the business logic, is
still tied to the API through the client. If your API changes and the
client/browser is still able to traverse it fine, but your business logic
breaks, does that _actually_ mean that the API is free to change? I don't
believe so.

~~~
rumanator
> My point is that even though they're loosely coupled, the API actually
> cannot change freely because the actual consumer of the API, the business
> logic, is still tied to the API through the client.

The main promise of REST is that following that particular application style
does indeed allow the API to freely change without breaking backwards
compatibility.

The main drawback of REST is that no one actually follows those principles.

With REST, the client is not tied to an API. The client seeks resources, and
relies on content discovery processes to determine how to access those
resources. The only endpoint that may be hard coded is a home/root endpoint,
and all other resources are accessible through it by following hypermedia.
With REST you care about the what, not the where.

> If your API changes and the client/browser is still able to traverse it
> fine, but your business logic breaks

This is where you're getting it wrong. REST is all about the interface. The
interface has zero to do with the business logic. If you have an interface
that allows you to access the same data but for some reason your business
logic breaks due to non-opersrional reasons (i.e. extra latency from the
content discovery process) you need to have a talk with whoever screwed that
up.

------
cryptos
There was a great article about the common misconceptions about REST recently:
[https://twobithistory.org/2020/06/28/rest.html](https://twobithistory.org/2020/06/28/rest.html)

The longer I think about it, the more I come to the conclusion that REST is
simply not useful for application development in general. It is no accident
that most APIs called "RESTful" by their creators are violating basic REST
principles. But REST has some useful attributes even if not used strictly -
caching comes to mind.

The question is: should we have another "standard" for web application
development? Something more like RPC? There are some approaches, but nothing
that I would call a broadly accepted standard. How should such a standard look
like?

~~~
mathw
Yes we should. We should have a standard which is actually a standard and
actually makes sense for what people are actually writing APIs to do.

gRPC would be a candidate, but the need for dev-side tooling to turn proto
files into code is a bit of a downer.

------
fbn79
Does JSON API ([https://jsonapi.org/](https://jsonapi.org/)) follow all this
rules? If not what rules is not followeb and why in your opinion?

------
lowercase1
I've never really seen a good explanation of why REST is a meaningful concept.
Why REST? Why these requirements? What do you mean stateless? What is bad
about deviating?

~~~
dvaun
I would suggest taking a skim through Chapter 5 of Roy Fielding's
dissertation[0] (where REST came from) to answer some of your questions.

As for "What do you mean stateless?", read this quote from the posted article:

> ...if the engine of application state (and hence the API) is not being
> driven by hypertext, then it cannot be RESTful and cannot be a REST API.

Why does he say this? Well, he was explicit about state in his
dissertation[1]:

> ...each request from client to server must contain all of the information
> necessary to understand the request, and cannot take advantage of any stored
> context on the server. Session state is therefore kept entirely on the
> client

[0]:
[https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

[1]: From Section 5.1.3
[https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_3)

~~~
gridlockd
This doesn't answer the question as to _why_ this is a good idea.

~~~
dvaun
That’s fair. I don’t have a decent explanation supporting why REST is a
meaningful concept. Rather, I focused on the other questions that could be
answered by the dissertation.

The choice to create an API in this fashion, without RPC and other things
mixed in, is up to the developer. Others have commented on this with their
arguments.

------
solipsism
This is equivalent to complaining that rap isn't music. The meanings of words
change, sometimes in ways we consider irrational or inconvenient in various
ways. Complaining about it never seems to help.

I long ago stopped complaining to people in this forum about the difference
between "it's" and "its". In response, please stop trying to reclaim the term
REST. It's long gone.

~~~
macca321
This is an article from 2008 by the person who invented REST.

