8 ms·

REST APIs must be hypertext-driven (2008)

27 points by dvaun 6y ago

fbn79 6y ago
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 6y ago
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 6y ago
  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_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... [1]: From Section 5.1.3 https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_3 https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
  - gridlockd 6y ago
    This doesn't answer the question as to why this is a good idea.
    - dvaun 6y ago
      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.
- noisem4ker 6y ago
  >What do you mean stateless? The server doesn't keep track of the state of client sessions. Each request is handled individually. This is an advantage as memory can be saved and requests originating from any client session can be handled by any server instance.
  - motogpjimbo 6y ago
    That is also possible in a stateful system, simply by storing user sessions in an independent session server.
- solipsism 6y ago
  What is bad about deviating? Nothing. These concepts were developed for the web. Not APIs on the web, but HTTP itself. A vast, global, decentralized network of heterogeneous machines. Fielding's dissertation doesn't argue that REST is good for all protocols and use cases, only ones that share those qualities. From Fielding's dissertation: Some architectural styles are often portrayed as “silver bullet” solutions for all forms of software. However, a good designer should select a style that matches the needs of a particular problem being solved. Also... REST is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction This prescription that every API needs to have these qualities is pure cargo culting.
  - rumanator 6y ago
    > These concepts were developed for the web. Not APIs on the web, but HTTP itself. This assertion is just plain wrong. REST is an architectural principle focused on providing APIs for web services, and Roy Fielding was quite vocal in making it extremely clear that there is nothing in REST that is HTTP-specific, let alone makes it tied to HTTP. REST is an architectural style that relied on the concept of resources, which should be linkable. That's it.
    - afiori 6y ago
      there is nothing http (or HTML) specific in REST, but REST itself is specific to the domain problem where http and HTML are used
      - rumanator 6y ago
        What domain problem is that? Communicating through a network?
        afiori 6y ago
        it is the domain of CDN-like servers
dozzman 6y ago
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 6y ago
  > 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.
  - cryptos 6y ago
solipsism 6y ago
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 6y ago
  This is an article from 2008 by the person who invented REST.
cryptos 6y ago
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 6y ago
  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.
  - deleted 6y ago
    [deleted]

27 points by dvaun 6y ago

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 6y ago

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 6y ago
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_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... [1]: From Section 5.1.3 https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_3 https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
- gridlockd 6y ago
  This doesn't answer the question as to why this is a good idea.
  - dvaun 6y ago
    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.
noisem4ker 6y ago
>What do you mean stateless? The server doesn't keep track of the state of client sessions. Each request is handled individually. This is an advantage as memory can be saved and requests originating from any client session can be handled by any server instance.
- motogpjimbo 6y ago
  That is also possible in a stateful system, simply by storing user sessions in an independent session server.
solipsism 6y ago
What is bad about deviating? Nothing. These concepts were developed for the web. Not APIs on the web, but HTTP itself. A vast, global, decentralized network of heterogeneous machines. Fielding's dissertation doesn't argue that REST is good for all protocols and use cases, only ones that share those qualities. From Fielding's dissertation: Some architectural styles are often portrayed as “silver bullet” solutions for all forms of software. However, a good designer should select a style that matches the needs of a particular problem being solved. Also... REST is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction This prescription that every API needs to have these qualities is pure cargo culting.
- rumanator 6y ago
  > These concepts were developed for the web. Not APIs on the web, but HTTP itself. This assertion is just plain wrong. REST is an architectural principle focused on providing APIs for web services, and Roy Fielding was quite vocal in making it extremely clear that there is nothing in REST that is HTTP-specific, let alone makes it tied to HTTP. REST is an architectural style that relied on the concept of resources, which should be linkable. That's it.
  - afiori 6y ago
    there is nothing http (or HTML) specific in REST, but REST itself is specific to the domain problem where http and HTML are used
    - rumanator 6y ago
      What domain problem is that? Communicating through a network?
      - afiori 6y ago
        it is the domain of CDN-like servers

dozzman 6y ago

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 6y ago
> 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.
- cryptos 6y ago

solipsism 6y ago

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 6y ago
This is an article from 2008 by the person who invented REST.

cryptos 6y ago

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 6y ago
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.
- deleted 6y ago
  [deleted]