Clarify on the maturity level

[odrotbohm]

You seem to misinterpret the semantics of the Richardson Maturity model. I clearly describes the REST architectural style as achieved if Level 3 is reached. The graphic is pretty precise on that. Also, note how the discussion of e.g. Level 0 describes the API to be an RCP one. So if — as you seem to imply — levels below 3 were already describing REST, that creates a contradiction.

Ironically, this is even directly stated in the summary of the article (emphasis mine):

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. Like many terms in software, REST gets lots of definitions, but since Roy Fielding coined the term, his definition should carry more weight than most.

Taking a step back, it seems what you're describing in the wiki is how to build decent HTTP APIs. That's just fine and probably a good thing to have if you have a lot of teams having to build these kinds of APIs. However, there's not need to label them REST if you're not actually adhering to the concept for two reasons:

1. If you tell people: "Here are our REST APIs", people will expect them to produce the qualities exposed by a REST API, e.g. evolvability. By skipping the parts of REST that actually produce those qualities, you basically disappoint your consumers.
2. You contribute to the wrong impression of what the architectural style of REST actually is, what it makes up.

I guess this makes me one of those "experts" that like to get into "religious discussions". I can live with that impression, but actually would just like to maintain semantics in technical terms as I wonder how are we supposed to really discuss things seriously if we're just bending every technological concept to what suits us or is en vogue these days.

[dsebastien]

Thanks @olivergierke.

We've published this design guide as open source for a good reason, we wanted to share what we did so far, but more importantly we wanted to learn and improve.

I'm not really interested in "religious" discussions, but I do care about semantics and correctness. You're right, I did actually think level 2 was already "RESTful" enough somehow. That happens when you read too many technical articles.. :)

I guess we should rename this guide to REST-ish or REST-like as it indeed does not fully respect all the constraints.

Although I do think that we're really not far from being actually RESTful. Also, we could probably add hypermedia to our design and without requiring a lot of changes.

[odrotbohm]

Thanks for taking the feedback into account! And happy coding! 🙃