48 ms·

Richardson Maturity Model

42 points by jeremylevy 4y ago

bazoom42 4y ago
Level 2 is good for API’s, level 3 is good for hypermedia browsed by a human.
- samwillis 4y ago
  Level 3 combined with HTML fragments as the response representation (rather than JSON or XML) is the fundamental idea behind many "HTML over the wire" toolkits such as HTMX. https://htmx.org/ https://htmx.org/
- 0xbadcafebee 4y ago
  Level 3 is still good for APIs. Humans don't really come into it... they're just clicking on pictures of cats.
flanked-evergl 4y ago
I would love to see some real world use cases of level 3, both for machine to machine use and for human to machine use.
- JimDabell 4y ago
  The World-Wide Web.
  - baq 4y ago
    Dynamically generated HTML as a response of an HTTP server! Preposterous! And what else? Maybe a scripting language so the user can interact with the client without having to contact the server? Insane!
JimDabell 4y ago
Calling an API without hypermedia a “level two REST API” is like calling a lettuce and tomato sandwich a “level two BLT”. You’re missing an intrinsic piece of the puzzle and anybody actually expecting a BLT is going to be disappointed. Why are people so adamant that they absolutely must call non-REST APIs “REST”? Names are free, you don’t have to hijack the name of something else!
- stanleydrew 4y ago
  > Why are people so adamant that they absolutely must call non-REST APIs “REST”? It's good for marketing I guess? A while ago REST took on connotations of "simple" and "clean", mostly in comparison to SOAP. So people will probably think more highly of your API if you call it REST.
  - mannykannot 4y ago
    With resume-padding being one aspect of marketing.
- baq 4y ago
  they say REST, they mean 'transport over HTTP and JSON payload'
  - marcosdumay 4y ago
    Nobody ever understood what REST means. The "standard" creator choosing not to document its meaning really didn't help. So, yeah, REST means whatever people use it for, that is 'HTTP services with JSON payload'. That's the actually valuable part of it anyway, the meaning that was documented after everybody started using it wrong is a synonym for the web, and we already have a name for it.
    - JimDabell 4y ago
      > The "standard" creator choosing not to document its meaning really didn't help. REST isn’t a standard, it’s an architectural style. And I’m not sure how you can say that the author chose not to document its meaning when the name “REST” originated with the author’s PhD dissertation.
raverbashing 4y ago
I'll say that the religious approach some take with REST is weird to me. Apparently there's some promised utopia behind getting REST perfect but in the end, nobody does it right but everybody makes it work for their case Getting the linkrels back is great, but it is up to your frontend to interpret them and display them back. There is no "magic" there because only humans know what does cancel/change mean, not the computers
- schnable 4y ago
  It's a fair point, but there is value in having those URLs constructed by the server rather than the client. The server can shift the path and params to make changes without the client having to make updates.
  - hbrn 4y ago
    No, there's illusion of value: 1. Paths are changed extremely rarely. Optimizing architecture for something that happens once a year is not a good idea. The cost of changing paths manually is pretty much always lower than the cost of HATEOAS. 2. You still want redirects from the old paths, because clients keep old paths in memory until refresh (which you don't control). 3. Typically when paths are changed, it also affects the entry point, so client still needs to be updated.
    - schnable 4y ago
      It depends on your use case. I have resolved critical bugs for mobile apps quickly server side using HATEOS by doing things that sticking extra parameters on a URL or rerouting traffic. The alternative would be updating multiple clients, QAing them, and getting them through app store reviews. If the clients aren't within your control even that isn't possible.
      - hbrn 4y ago
        Sure, HATEOAS can be useful when you don't have control over clients or over the routes. Which is exactly the case for WWW: clients are browsers (not developed by you), and URLs can be images from another server (not owned by you). And while it can happen for APIs, those cases are exception rather than the rule. That's why it's so annoying when REST purists are trying to shame people who are actually doing the right thing. I would also be curious to learn how exactly sticking extra params would fix a critical bug. I can't help but wonder if bugs were caused by HATEOAS in the first place.
rileymat2 4y ago
> This allows us to invoke GETs safely any number of times in any order and get the same results each time. An important consequence of this is that it allows any participant in the routing of requests to use caching, which is a key element in making the web perform as well as it does. What conditions for a restful api does this come in handy? In most implementations I have had the requests are as quick to figure out if anything has changed as it is to return the result. The problem is not that a get changes the result, it is a post from some other client has changed it in the interim and you want the freshest data. Id imagine it is most useful in serving static content that has large payloads, which most of my apis don’t serve.
- schnable 4y ago
  Static content by definition doesn't change so this rule isn't for that case. Caching benefits even dynamic content, and dealing with cache invalidation is a separate problem than what is being discussed here. Your clients may always want the freshest content, but that often isn't scalable. If it is, you can put no expiration in your cache headers and let 'er rip. But you should still respect the idempotency of GET requests.

42 points by jeremylevy 4y ago

bazoom42 4y ago

Level 2 is good for API’s, level 3 is good for hypermedia browsed by a human.

samwillis 4y ago
Level 3 combined with HTML fragments as the response representation (rather than JSON or XML) is the fundamental idea behind many "HTML over the wire" toolkits such as HTMX. https://htmx.org/ https://htmx.org/
0xbadcafebee 4y ago
Level 3 is still good for APIs. Humans don't really come into it... they're just clicking on pictures of cats.

flanked-evergl 4y ago

I would love to see some real world use cases of level 3, both for machine to machine use and for human to machine use.

JimDabell 4y ago
The World-Wide Web.
- baq 4y ago
  Dynamically generated HTML as a response of an HTTP server! Preposterous! And what else? Maybe a scripting language so the user can interact with the client without having to contact the server? Insane!

JimDabell 4y ago

Calling an API without hypermedia a “level two REST API” is like calling a lettuce and tomato sandwich a “level two BLT”. You’re missing an intrinsic piece of the puzzle and anybody actually expecting a BLT is going to be disappointed. Why are people so adamant that they absolutely must call non-REST APIs “REST”? Names are free, you don’t have to hijack the name of something else!

stanleydrew 4y ago
> Why are people so adamant that they absolutely must call non-REST APIs “REST”? It's good for marketing I guess? A while ago REST took on connotations of "simple" and "clean", mostly in comparison to SOAP. So people will probably think more highly of your API if you call it REST.
- mannykannot 4y ago
  With resume-padding being one aspect of marketing.
baq 4y ago
they say REST, they mean 'transport over HTTP and JSON payload'
- marcosdumay 4y ago
  Nobody ever understood what REST means. The "standard" creator choosing not to document its meaning really didn't help. So, yeah, REST means whatever people use it for, that is 'HTTP services with JSON payload'. That's the actually valuable part of it anyway, the meaning that was documented after everybody started using it wrong is a synonym for the web, and we already have a name for it.
  - JimDabell 4y ago
    > The "standard" creator choosing not to document its meaning really didn't help. REST isn’t a standard, it’s an architectural style. And I’m not sure how you can say that the author chose not to document its meaning when the name “REST” originated with the author’s PhD dissertation.

raverbashing 4y ago

I'll say that the religious approach some take with REST is weird to me. Apparently there's some promised utopia behind getting REST perfect but in the end, nobody does it right but everybody makes it work for their case Getting the linkrels back is great, but it is up to your frontend to interpret them and display them back. There is no "magic" there because only humans know what does cancel/change mean, not the computers

schnable 4y ago
It's a fair point, but there is value in having those URLs constructed by the server rather than the client. The server can shift the path and params to make changes without the client having to make updates.
- hbrn 4y ago
  No, there's illusion of value: 1. Paths are changed extremely rarely. Optimizing architecture for something that happens once a year is not a good idea. The cost of changing paths manually is pretty much always lower than the cost of HATEOAS. 2. You still want redirects from the old paths, because clients keep old paths in memory until refresh (which you don't control). 3. Typically when paths are changed, it also affects the entry point, so client still needs to be updated.
  - schnable 4y ago
    It depends on your use case. I have resolved critical bugs for mobile apps quickly server side using HATEOS by doing things that sticking extra parameters on a URL or rerouting traffic. The alternative would be updating multiple clients, QAing them, and getting them through app store reviews. If the clients aren't within your control even that isn't possible.
    - hbrn 4y ago
      Sure, HATEOAS can be useful when you don't have control over clients or over the routes. Which is exactly the case for WWW: clients are browsers (not developed by you), and URLs can be images from another server (not owned by you). And while it can happen for APIs, those cases are exception rather than the rule. That's why it's so annoying when REST purists are trying to shame people who are actually doing the right thing. I would also be curious to learn how exactly sticking extra params would fix a critical bug. I can't help but wonder if bugs were caused by HATEOAS in the first place.

rileymat2 4y ago

> This allows us to invoke GETs safely any number of times in any order and get the same results each time. An important consequence of this is that it allows any participant in the routing of requests to use caching, which is a key element in making the web perform as well as it does. What conditions for a restful api does this come in handy? In most implementations I have had the requests are as quick to figure out if anything has changed as it is to return the result. The problem is not that a get changes the result, it is a post from some other client has changed it in the interim and you want the freshest data. Id imagine it is most useful in serving static content that has large payloads, which most of my apis don’t serve.

schnable 4y ago
Static content by definition doesn't change so this rule isn't for that case. Caching benefits even dynamic content, and dealing with cache invalidation is a separate problem than what is being discussed here. Your clients may always want the freshest content, but that often isn't scalable. If it is, you can put no expiration in your cache headers and let 'er rip. But you should still respect the idempotency of GET requests.