Comment by cryptonector

> the only clients that are evolvable enough to interface with a REST API can be categorized to these three types

You mention swagger. Swagger is an anti-REST tech. Defining a media type is the REST equivalent of writing a swagger API description.

If you can define an API in swagger, you can define one via a media type. It's just that the latter is generally not done because to do it requires a JSON schema (or similar) and people mostly don't use that or think of that as how one defines an API.

Boss: we need an API for XYZ

Employee: sure thing boss, I'll write it in swagger and implement by Friday!