Introspected REST: An Alternative to REST and GraphQL

- Sections 1-8 are a summary of REST, HATEOS, their problems, and reflections on the problem that every endpoint is `application/json` and not something more specific to the intended use case.

- Sections 9-11 discuss a variant of REST that doesn't use Media Type differentiation for capabilities, but rather composable nuggets of semantics called MicroTypes. The MicroType schemata is accessible through an introspection interface; one suggestion is to use (cacheable) OPTIONS. Clients would transmit their desired MicroTypes to an endpoint using the Accept-Type header.

If I'm reading this correctly, the author is suggesting the clients be allowed to specify the middleware chain used by the server to compose the response data (cf pagination, query, filter MicroTypes), and that these programmable chains are attached to every traditional REST endpoint collection. In one sense, this is an attempt to marry the resolver chain concept from GraphQL into the world of RESTish JSON APIs.

I think you could pull this off only with a dedicated server library because I don't see real world developers using this technique successfully on the current crop of HTTP webserver APIs. There's also the very real performance issues that come up when clients are allowed to control resolution; we see companies using GraphQL in production locking down the ability to do custom queries.

One thing GraphQL got right was focusing on the client tooling. If the client developers are bought in to the protocol/specification then the server developers will naturally come along. The reverse has not been true in my case.

This opinion is based on my experience building hypermedia APIs, consuming hypermedia APIs and helping with the HAL hypermedia spec.

The first sentence of TFA captures one of the most annoying things about REST discussions: "In this manifesto, we will give a specific definition of what REST is, according to Roy, and see the majority of APIs and API specs (JSONAPI, HAL etc) fail to follow this model."

At this point I've read or heard dozens of claims like this, that almost everyone is doing REST wrong. It's well past time to stop blaming all the REST implementers in the world for being too dumb to understand Fielding's brilliant vision. If most software developers can't get REST right, then either proponents have consistently done a crappy job explaining the idea, or it's not as great an idea as they think.

Skimming the table of contents, it looks like the authors have thought deeply about the problems with REST and come up with some well-reasoned solutions. So they're answering the "REST vs Introspected REST" question. But much more relevant to me is the "Introspected REST vs GraphQL" question. What would make someone choose this over GraphQL? Introspected REST has a lot of catching up to do to match GraphQL's tooling and market share.

Did you know WSDL has supported "REST"-like encoding of parameters in URLs and operations as HTTP verbs since 2001?

For example, our API needed a way to serve a different view of an existing model. How do I get the API to know which view to serve? When I asked around, they said the best way was to do /cars/1/prices, which I didn't like because I feel it breaks REST. There's no price model to the car, prices are fields of cars, at least for now.

I had to think for a few seconds before coming up with just using a query parameter to set which view to serve, /cars/1?view=pricelist, preserving REST. But most coders just take the first thing that comes to mind, and then wonder why their applications are so messy after a few years.

Coders seem to not want to bother learning how existing solutions are supposed to work before jumping to a half-baked newer solution just because it seems more intuitive. If you understand REST, then you can see how GraphQL can improve certain aspects of API interaction.

But it's not a panacea any more than React is. If you understood how HTML, CSS, and Javascript are supposed to work, then you can see how React improves on it. But if you can't then your React applications will be just as horrendous as your jQuery ones were.

For starters, a lot of people are looking for a TL;DR. There is no such thing. Same with tooling.

This is an open publication and should be considered as is. The intention was to come up with a better architectural design than REST, reusing existing Internet architecture. And that was the real challenge. Because REST and HTTP have been built almost by the same person. Bending existing Internet architecture to fit another architectural style for networked services is extremely difficult, but apparently not impossible.

GraphQL for instance, uses HTTP just for the transport layer. That's a big assumption to make there, anyone can build very flexible stuff if you are about to re-design everything HTTP gives on top of HTTP.

Another note is the reason that it takes so much time to get to the actual model (section 9) is to make sure the reader understands what is REST and where REST fails. And I haven't really seen any other document/publication explaining REST so extensively. So for those who are complaining that none gives a definition of REST, then go through section 1-6 and you should have it.

Last but not least, Introspected REST is compatible with existing REST architecture, it just makes it more robust and flexible. So for the tiny hello world example, it doesn't really make any difference other than exposing some meta data through the OPTIONS endpoint, like the (JSON) schema and the linking. But for complex APIs it should give huge advantages compared to REST.

And again: this is an open publication. From that to actual implementation there are many steps needed to be taken (for starters defining the necessary microtypes).

That said , even if the arguments in this spec are solid the entire industry are sold itself to GraphQL.

GraphQL has won and it won't change.