The case for introspection and microtypes

[Flogex]

I've spent some time thinking about Introspected REST lately and want to summarize my current understanding, starting from this Roy Fielding quote

However, a good designer should select a style that matches the needs of the
particular problem being solved

In my understanding, the particular problem Introspected REST tries to solve is a pragmatic one. Introspected REST is an API style which can deal with hypermedia-ready clients as well as with clients which do not use hypermedia, but are tighter coupled to the server. Following the introspection principle, the latter do only receive the data without any metadata. The benefits are higher performance and less complexity, since the clients don't have to deal with metadata/hypermedia.

But in my opinion, these benefits come at the price of lower evolvability. Because now you acknowledge that there are clients which may break if you change your API, although other clients (the ones using hypermedia) would not break. But with this you are back to the current state of the art, namely versioning your API to allow old clients to still successfully communicate with the API. And if you create a new version for your API, clients which do utilize hypermedia have to be adjusted, too.

I understand that, although you create a level 3 REST API, it is likely that there are also clients which do not use hypermedia perfectly. But at least you could pretend they do not exist. 😜 Well, I don't have an idea how an approach could look like where you satisfy both kinds of clients. But I don't think that Introspected REST solves this.

---

Besides introspection there are also microtypes. BTW: Why do you need the introspection principle if there are microtypes? Couldn't you achieve the same results with microtypes only? Clients could just not accept any introspection microtype and hence the server will not send any static metadata.

As far as I understand it, microtypes can solve a similar problem like the one which led to the creation of GraphQL or patterns like BFF: That you have a bunch of different clients with different requirements, and they can't be served by a single one-size-fits-all REST API. If clients can choose from a set of microtypes, the API can serve these different clients. One client can display a lot of information and might select the microtype which includes a lot of details of the items in a list. Another one only wants the very basic information about each item and therefore selects another microtype. I mean, this may be hard to implement on the server, but in principle you could offer a microtype for every possible use case or requirement, but still have a single API. Of course, you don't achieve such a fine-grained selection of the data needed as with GraphQL, but it is more fine-grained than with REST. And yes, there are issues like cacheability and so on, but maybe it's a pragmatic middle ground, because you still receive most of the benefits of REST.

How accurate do you think my description is? Is what I am describing the essence of Introspected REST or am I missing something? I am looking forward to your opinion on this.