Richardson Maturity Model | Hacker News Reader

Richardson Maturity Model

martinfowler.com

42 pointsjeremylevy30 comments

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

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.

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.

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.

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.

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

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/

Level 3 is still good for APIs. Humans don't really come into it... they're just clicking on pictures of cats.

> 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.

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.

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!

> 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.

With resume-padding being one aspect of marketing.

they say REST, they mean 'transport over HTTP and JSON payload'

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.

> 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.

Fielding's dissertation was about WWW. It turns out that 20+ years later, there's a new portion of WWW (web APIs) where hypermedia is not that useful.

One big difference is that WWW clients are browsers, which you don't develop yourself. API clients are typically developed by the same team that builds the API.

Losing interoperability is detrimental for WWW (browser wars), but turns out when you are the consumer of your own API, interoperability is not important at all.

That is what it does mean. Unfortunately creators of a term do not get to control its usage I suspect the number of Roy Fielding approved implementations would likely be very small. Furthermore, I don’t think it matters - there is no sin in RPC.

The article doesn't say to call an API without hypermedia a "level 2 REST API"; in fact it says the exact opposite.

> I should stress that the RMM, while a good way to think about what the elements of REST, is not a definition of levels of REST itself. Roy Fielding has made it clear that level 3 RMM is a pre-condition of REST.

Sorry, there’s a little bit of background knowledge needed here – this is an old and very well-known article. The article itself is correct, but nevertheless, after it became popular, a tonne of people started using the terminology “level two REST” to justify calling APIs that were not REST “REST”. I’m more responding to that than the article itself.

It's one of the very annoying quirks of language that if enough people call an apple an orange, suddenly "orange" also means "apple". I hate it but there's not a lot we can do about it.

> they absolutely must call non-REST APIs “REST”

What would you call it though? If the only thing we call REST is what's called a "level 3 REST" API in this article, then virtually nothing would be called REST.

Call it "JSON API", that pinpoints all important characteristics of most "REST" APIs lacking HATEOAS.

Because 99% of REST value is coming from structuring your API around Resources and Verbs.

HATEOAS is for snake oil sellers and their religious followers, who want to feel superior.

Having developed both HATEOAS and non-HATEOAS systems. The HATEOAS systems were categorically less brittle, easier to change, and had faster turn around times. The immediate benefits of resources and verbs in greenfield development are easy to spot, but ongoing system evolution is where HATEOAS's value prop shines.

With HATEOAS, are you just not pushing complexity of change into the client/consumer?

It's a common misconception that complexity is a zero-sum game.

There are gains to be made from certain design decisions and HATEOAS in my experience with multiple front end teams and multiple back end teams working in HATEOAS-land is that the HATEOAS systems were able to address ongoing systems evolution in ways that when complexity did come up, it was easier to address and manage.

I'm not here to proposition it as a silver bullet, or have quantitative data to substantiate it, but in my experience the ease of ongoing system architectural evolution in both client and server realms made up for the difference in tension between the two camps.

One example of a tension in HATEOAS is the complaint from clients that they can't hardcode links like they did before. One of the points, obviously, of HATEOAS is the ability to represent state using hypermedia[links]. One terrible thing the backend could do is make clients traverse multiple resources to get a url to perform an action elsewhere[1].

Rather than saying "tough luck, deal with it," communication workflows and architecture was adjusted so that for most workflows, the required urls were made available as a natural part of accessing resources needed to accomplish the workflow.

Does this require some work on the client to extract the link and use it for the next step in the workflow? yes. Do the other benefits make up for it? It did in my org. It might in yours. Part of being a good architect is making that decision correctly more often than not.

1. I'm being a bit loose with terminology, but I hope it helps rather than detracts from understanding.

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.

The World-Wide Web.

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!

Reply on news.ycombinator.com