[JimDabell]

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!

[hbrn]

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.

[kelseyfrog]

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.

[pan69]

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

[kelseyfrog]

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.

[0xbadcafebee]

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.

[gjm11]

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.

[JimDabell]

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.

[stanleydrew]

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

With resume-padding being one aspect of marketing.

[baq]

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

[marcosdumay]

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]

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

[hbrn]

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.

[osigurdson]

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.

[commandlinefan]

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

[Isognoviastoma]

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