6 ms·

Introspected REST: An alternative to REST and GraphQL

122 points by nedp 8y ago

bgrainger 8y ago
Previously: https://news.ycombinator.com/item?id=15140908 https://news.ycombinator.com/item?id=15140908 https://news.ycombinator.com/item?id=15211604 https://news.ycombinator.com/item?id=15211604 https://news.ycombinator.com/item?id=18422095 https://news.ycombinator.com/item?id=18422095
yardstick 8y ago
Really needs a TL;DR style summary at the start. Or at least a couple brief examples to show the approach in a concise manner. While I could spend significant time reading the entire manifesto, I’d appreciate a way to see up front if it’s worthwhile doing so. The author has rejected similar calls before: https://news.ycombinator.com/item?id=18425581 https://news.ycombinator.com/item?id=18425581 but I truly think it would be beneficial to a lot of potential readers.
- geezerjay 8y ago
  If the author can't be bothered to explain his idea in intelligible and clear terms, and also is unable to present a concrete example showcasing his proposed approach, then there is no point to waste time reading a manifesto as the creators themselves are incapable of leveraging the idea to produce any result.
  - jondubois 8y ago
    I also agree. If something cannot be explained in simple terms, then there is no way that it will be understood by enough people to actually trigger a change in collective behavior. There needs to be some kind of marketing to give people an incentive to read the whole thing. The marketing can be technical but it needs to be short and it needs to appeal to a common set of principles which people already have.
- megakid 8y ago
  Came here to write this. Agree
  - quickthrower2 8y ago
    Yep I came here for the tldr to see if it is worth reading the rest of the article.
cryptica 8y ago
I think that a big part of the problem is that HTTP was initially designed for transfering static files and static data over potentially unauthenticated connections. It wasn't designed to deal with application data that is complex and changes frequently with many concurrent users. I think that HTTP has been popular for so long that many people just refuse to admit that it's not suitable for handling complex dynamic data. They will go to desperate extremes to try to make it work; e.g. GraphQL over HTTP or Introspected REST. To deal with complex, fast changing data, we need to step away from HTTP and look towards simpler bidirectional connections as a starting point (e.g. WebSockets).
- elcomet 8y ago
  I'm not so sure about this. The methods POST and PUT for example reflect the intention of updating data on a server. Also, HTTP is just a transfer protocol, I see no problem building abstractions on top of it to handle data transfers for complex applications. Could you explain with more details what properties of HTTP makes it hard to deal with complex data?
  - jondubois 8y ago
    > Could you explain with more details what properties of HTTP makes it hard to deal with complex data? There are a few but one of the first that comes to mind is what happens if two users modify different fields/properties of the same resource at the same time? If you want to support concurrent editing by multiple users, you need a way to either automatically resolve conflicts or to avoid conflicts altogether. With REST over HTTP, because updates typically involve overwriting the whole resource in a single POST or PUT, one user will fully overwrite the changes made by the other user; even if they were editing different fields of the same resource.
    - spinningarrow 8y ago
      But is that a failing of HTTP? “Updates typically involve overwriting the whole resource” because of how many APIs implement updates; they could for example use PATCH instead. I believe GraphQL mutations also allow updating individual fields.
LoSboccacc 8y ago
"Basically misunderstood REST and added back the discoverability that was there to begin with" approach. You can see from his "proper" implementation of rest that his test understanding is partial at best, for example the user object doesn't return links to change his state (i.e. suspend, delete) not the users resource exposes an endpoint to add a user. Then he added it in the "introspected" approach, but it's nothing novel.
- pojzon 8y ago
  I think that if discoverability would be there from the start, we wouldnt have things like Hateoas or GraphQL developed in the first place - why do that if its there ? First example shows how most APIs on Internet look like right now with all possible enhancments after that - presenting that they are far from ideal. After that is a section which shows how to limit human interaction with API because it should be "machine to machine" designed and how it can be accomplished using the new approach. Tho i understand its hard to get at first, some TLDR wouldnt hurt.
  - icebraining 8y ago
    I think that if discoverability would be there from the start, we wouldnt have things like Hateoas HATEOAS is there from the start; in fact, it's an integral part of the concept of REST.
  - naasking 8y ago
    > I think that if discoverability would be there from the start, we wouldnt have things like Hateoas HATEOAS is discoverable. That's the whole point of placing hypermedia as a central tenet of REST.
  - LoSboccacc 8y ago
    > I think that if discoverability would be there from the start, we wouldnt have things like Hateoas Off you go into the heap of people that don't understand rest. Hateoas is in the original spec, if you haven't read it. > Tho i understand its hard to get at first, some TLDR wouldnt hurt. Maybe some reading of basic etiquette would help there too.
gcb0 8y ago
my favorite part, every time this shows up here, is that an example of a simple api with all the info the client needs to understand the data is: """application/vnd.weather+yaml Media Type that is only supposed to provide a single attribute with its value, as Integer: temperature: 25""" which completely ignores the unit ;) the fact that no human would ever know the actual temperature, shows how disconnected from humanity most protocol design committees are.
- cies 8y ago
  temperature_in_c would do, so would latency_in_ms, or distance_in_km. I think an API is not for humans in general, but for the specific sub-group of humans that are programmers (and machines obviously). So some disconnect from humanity as a whole is, I believe, acceptable in API design.
pojzon 8y ago
As someone who simply dislikes the half-baked approach of HATEoas and its alternatives, this anew approach suits me better.
- icebraining 8y ago
  Why is HATEOAS (which is simply a description of how sites work) half-baked?
  - pojzon 8y ago
    Manifest contains answer to this question in the section dedicated to hateoas
jeremycw 8y ago
REST is one of the most blogged about, argued over bike sheds in tech. Once you stop agonizing over status codes, media types, routes being nouns, resources, etc. it becomes surprisingly easy to be productive with HTTP. There are just a few simple rules to follow. GETs shouldn't make changes. PUTs should make idempotent changes. 2xx status codes are for success. 4xx and 5xx are for failure.
- naasking 8y ago
  Sure, you can be productive by just using http as an RPC channel, but it's fragile. That's part of what REST covers.
- geezerjay 8y ago
  You're describing RPC over HTTP. REST does rely on resources and does use a limited set of CRUD commands to operate over the resources, but REST also requires automatic discovery from a single starting resource/endpoint (see HATEOAS).
giardini 8y ago
This article has been posted and re-posted 4 times on ycombinator starting a year ago: https://hn.algolia.com/?query=alternative%20to%20REST%20and%20GraphQL&sort=byPopularity&prefix&page=0&dateRange=all&type=story https://hn.algolia.com/?query=alternative%20to%20REST%20and%... REST works great without an "introspected REST". The repeated reposting of "Introspected REST" here reminds me of the Far Side's Little Bang cartoon: https://dakiniland.files.wordpress.com/2013/05/little-bang-theory.jpg https://dakiniland.files.wordpress.com/2013/05/little-bang-t...
- RomanPushkin 8y ago
  > REST works great without an "introspected REST" Cars work great without electric engine Bikes work great without pedals
dsego 8y ago
Previous discussion, only a month ago https://news.ycombinator.com/item?id=18422095 https://news.ycombinator.com/item?id=18422095
apo 8y ago
The biggest misconception to get over is that REST has nothing to do with HTTP. You can implement REST over any transport protocol. Clean URLs, status codes, and methods are irrelevant. Everything revolves around media types. Your service provides resources with well-defined media types. Your clients send requests with recognized media types. That said, this simple architectural style is exceedingly difficult to pull off. Most of what people call "REST" is nothing more than JSON-RPC. There's nothing wrong with that, but Fielding invented REST, so he gets to say what it is. Fielding's dissertation, where REST is defined, isn't much help though. The biggest problem is its highly abstract nature with few clarifying examples of what REST is and is not. This article provides these examples, and so should compliment Fielding's dissertation.
honkycat 8y ago
GraphQL rules, will never go back to rest if I can help it.

122 points by nedp 8y ago

Previously: https://news.ycombinator.com/item?id=15140908 https://news.ycombinator.com/item?id=15140908 https://news.ycombinator.com/item?id=15211604 https://news.ycombinator.com/item?id=15211604 https://news.ycombinator.com/item?id=18422095 https://news.ycombinator.com/item?id=18422095

yardstick 8y ago

Really needs a TL;DR style summary at the start. Or at least a couple brief examples to show the approach in a concise manner. While I could spend significant time reading the entire manifesto, I’d appreciate a way to see up front if it’s worthwhile doing so. The author has rejected similar calls before: https://news.ycombinator.com/item?id=18425581 https://news.ycombinator.com/item?id=18425581 but I truly think it would be beneficial to a lot of potential readers.

geezerjay 8y ago
If the author can't be bothered to explain his idea in intelligible and clear terms, and also is unable to present a concrete example showcasing his proposed approach, then there is no point to waste time reading a manifesto as the creators themselves are incapable of leveraging the idea to produce any result.
- jondubois 8y ago
  I also agree. If something cannot be explained in simple terms, then there is no way that it will be understood by enough people to actually trigger a change in collective behavior. There needs to be some kind of marketing to give people an incentive to read the whole thing. The marketing can be technical but it needs to be short and it needs to appeal to a common set of principles which people already have.
megakid 8y ago
Came here to write this. Agree
- quickthrower2 8y ago
  Yep I came here for the tldr to see if it is worth reading the rest of the article.

cryptica 8y ago

I think that a big part of the problem is that HTTP was initially designed for transfering static files and static data over potentially unauthenticated connections. It wasn't designed to deal with application data that is complex and changes frequently with many concurrent users. I think that HTTP has been popular for so long that many people just refuse to admit that it's not suitable for handling complex dynamic data. They will go to desperate extremes to try to make it work; e.g. GraphQL over HTTP or Introspected REST. To deal with complex, fast changing data, we need to step away from HTTP and look towards simpler bidirectional connections as a starting point (e.g. WebSockets).

elcomet 8y ago
I'm not so sure about this. The methods POST and PUT for example reflect the intention of updating data on a server. Also, HTTP is just a transfer protocol, I see no problem building abstractions on top of it to handle data transfers for complex applications. Could you explain with more details what properties of HTTP makes it hard to deal with complex data?
- jondubois 8y ago
  > Could you explain with more details what properties of HTTP makes it hard to deal with complex data? There are a few but one of the first that comes to mind is what happens if two users modify different fields/properties of the same resource at the same time? If you want to support concurrent editing by multiple users, you need a way to either automatically resolve conflicts or to avoid conflicts altogether. With REST over HTTP, because updates typically involve overwriting the whole resource in a single POST or PUT, one user will fully overwrite the changes made by the other user; even if they were editing different fields of the same resource.
  - spinningarrow 8y ago
    But is that a failing of HTTP? “Updates typically involve overwriting the whole resource” because of how many APIs implement updates; they could for example use PATCH instead. I believe GraphQL mutations also allow updating individual fields.

LoSboccacc 8y ago

"Basically misunderstood REST and added back the discoverability that was there to begin with" approach. You can see from his "proper" implementation of rest that his test understanding is partial at best, for example the user object doesn't return links to change his state (i.e. suspend, delete) not the users resource exposes an endpoint to add a user. Then he added it in the "introspected" approach, but it's nothing novel.

pojzon 8y ago
I think that if discoverability would be there from the start, we wouldnt have things like Hateoas or GraphQL developed in the first place - why do that if its there ? First example shows how most APIs on Internet look like right now with all possible enhancments after that - presenting that they are far from ideal. After that is a section which shows how to limit human interaction with API because it should be "machine to machine" designed and how it can be accomplished using the new approach. Tho i understand its hard to get at first, some TLDR wouldnt hurt.
- icebraining 8y ago
  I think that if discoverability would be there from the start, we wouldnt have things like Hateoas HATEOAS is there from the start; in fact, it's an integral part of the concept of REST.
- naasking 8y ago
  > I think that if discoverability would be there from the start, we wouldnt have things like Hateoas HATEOAS is discoverable. That's the whole point of placing hypermedia as a central tenet of REST.
- LoSboccacc 8y ago
  > I think that if discoverability would be there from the start, we wouldnt have things like Hateoas Off you go into the heap of people that don't understand rest. Hateoas is in the original spec, if you haven't read it. > Tho i understand its hard to get at first, some TLDR wouldnt hurt. Maybe some reading of basic etiquette would help there too.

gcb0 8y ago

my favorite part, every time this shows up here, is that an example of a simple api with all the info the client needs to understand the data is: """application/vnd.weather+yaml Media Type that is only supposed to provide a single attribute with its value, as Integer: temperature: 25""" which completely ignores the unit ;) the fact that no human would ever know the actual temperature, shows how disconnected from humanity most protocol design committees are.

cies 8y ago
temperature_in_c would do, so would latency_in_ms, or distance_in_km. I think an API is not for humans in general, but for the specific sub-group of humans that are programmers (and machines obviously). So some disconnect from humanity as a whole is, I believe, acceptable in API design.

pojzon 8y ago

As someone who simply dislikes the half-baked approach of HATEoas and its alternatives, this anew approach suits me better.

icebraining 8y ago
Why is HATEOAS (which is simply a description of how sites work) half-baked?
- pojzon 8y ago
  Manifest contains answer to this question in the section dedicated to hateoas

jeremycw 8y ago

REST is one of the most blogged about, argued over bike sheds in tech. Once you stop agonizing over status codes, media types, routes being nouns, resources, etc. it becomes surprisingly easy to be productive with HTTP. There are just a few simple rules to follow. GETs shouldn't make changes. PUTs should make idempotent changes. 2xx status codes are for success. 4xx and 5xx are for failure.

naasking 8y ago
Sure, you can be productive by just using http as an RPC channel, but it's fragile. That's part of what REST covers.
geezerjay 8y ago
You're describing RPC over HTTP. REST does rely on resources and does use a limited set of CRUD commands to operate over the resources, but REST also requires automatic discovery from a single starting resource/endpoint (see HATEOAS).

giardini 8y ago

This article has been posted and re-posted 4 times on ycombinator starting a year ago: https://hn.algolia.com/?query=alternative%20to%20REST%20and%20GraphQL&sort=byPopularity&prefix&page=0&dateRange=all&type=story https://hn.algolia.com/?query=alternative%20to%20REST%20and%... REST works great without an "introspected REST". The repeated reposting of "Introspected REST" here reminds me of the Far Side's Little Bang cartoon: https://dakiniland.files.wordpress.com/2013/05/little-bang-theory.jpg https://dakiniland.files.wordpress.com/2013/05/little-bang-t...

RomanPushkin 8y ago
> REST works great without an "introspected REST" Cars work great without electric engine Bikes work great without pedals

dsego 8y ago

Previous discussion, only a month ago https://news.ycombinator.com/item?id=18422095 https://news.ycombinator.com/item?id=18422095

apo 8y ago

The biggest misconception to get over is that REST has nothing to do with HTTP. You can implement REST over any transport protocol. Clean URLs, status codes, and methods are irrelevant. Everything revolves around media types. Your service provides resources with well-defined media types. Your clients send requests with recognized media types. That said, this simple architectural style is exceedingly difficult to pull off. Most of what people call "REST" is nothing more than JSON-RPC. There's nothing wrong with that, but Fielding invented REST, so he gets to say what it is. Fielding's dissertation, where REST is defined, isn't much help though. The biggest problem is its highly abstract nature with few clarifying examples of what REST is and is not. This article provides these examples, and so should compliment Fielding's dissertation.

honkycat 8y ago

GraphQL rules, will never go back to rest if I can help it.