What Does "REST API" Mean To You?

I now understand the glory of REST to be de-coupled clients and servers, achievable only because of hypertext (if you have another way to keep clients and servers de-coupled, let's hear it!).

Unfortunately many of my peers in the industry have co-opted the term and now to them it means something else: JSON payloads, proper usage of response status codes, nouns in the URI, and HTTP verbs mapped to database CRUD operations. This is keeping me very busy at work because this secondary definition didn't achieve the promised de-coupling from the original definition. Making a change on the server becomes a nightmare due to fear of breaking existing clients. Changes have to be rolled out carefully, in tandem, etc. There's even talk amongst some in the industry of versioning the API, gasp!

I think the lack of clear RESTful API examples is to blame. Not that they're few and far between, they just don't fit that secondary definition and so they're immediately dismissed. The web browser is a perfect example of a RESTful client: your web browser has no special understanding of what wikipedia means when it uses an anchor tag vs. what Google thinks the anchor tag should mean. In that sense, it is de-coupled from any server that serves up HTML. That's all possible because HTML is hypertext.

Sprinkling in some links into the secondary definition only goes so far. Unfortunately what's missing is a way to instruct clients on how to make a POST request, like the venerable HTML form tag. We came close with openapi/swagger, but unfortunately many treat the swagger as documentation, not hypermedia. In other words, a client is coded up to be coupled to what the documentation says right now and not what it might say in the future.

Too bad there isn't another buzzword for the secondary definition to distinguish it from the original. I suppose JSON-RPC is the best we have.