Introspected REST: An Alternative to REST and GraphQL

It looks like the meat starts at section 9.<p>- Sections 1-8 are a summary of REST, HATEOS, their problems, and reflections on the problem that every endpoint is `application&#x2F;json` and not something more specific to the intended use case.<p>- Sections 9-11 discuss a variant of REST that doesn&#x27;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.<p>If I&#x27;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.<p>I think you could pull this off only with a dedicated server library because I don&#x27;t see real world developers using this technique successfully on the current crop of HTTP webserver APIs. There&#x27;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.

There is some good stuff in here, but it misses the biggest pain point developers face when trying to make a robust hypermedia API: tooling. There is a lack of tooling on the server side and almost no tooling on the client side. The amount of effort required to serve a RESTful API requires a lot of upfront investment. Then convincing the client developers to take advantage of the hypermedia affordances requires a lot of time and energy. If one does manage to convince them, the client tooling requires even more upfront investment. The only attempt at client tooling I have seen is the work done by Mike Amundsen.<p>One thing GraphQL got right was focusing on the client tooling. If the client developers are bought in to the protocol&#x2F;specification then the server developers will naturally come along. The reverse has not been true in my case.<p>This opinion is based on my experience building hypermedia APIs, consuming hypermedia APIs and helping with the HAL hypermedia spec.

Also submitted a couple months ago. Only got a few comments back then: <a href="https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=15211604" rel="nofollow">https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=15211604</a><p>The first sentence of TFA captures one of the most annoying things about REST discussions: &quot;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.&quot;<p>At this point I&#x27;ve read or heard dozens of claims like this, that almost everyone is doing REST wrong. It&#x27;s well past time to stop blaming all the REST implementers in the world for being too dumb to understand Fielding&#x27;s brilliant vision. If most software developers can&#x27;t get REST right, then either proponents have consistently done a crappy job explaining the idea, or it&#x27;s not as great an idea as they think.<p>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&#x27;re answering the &quot;REST vs Introspected REST&quot; question. But much more relevant to me is the &quot;Introspected REST vs GraphQL&quot; question. What would make someone choose this over GraphQL? Introspected REST has a lot of catching up to do to match GraphQL&#x27;s tooling and market share.

The developers that would hypothetically adopt and implement a new paradigm like this would probably love to just see some straight forward examples of client and server usage

Can we just have back SOAP&#x2F;WSDL and return to rational design and interoperability, or at least limit &quot;REST&quot; to a web facade? I think after 10-15 years of mucking around with &quot;REST&quot; (or what people think it is, as rightfully pointed out in TFA) it&#x27;s very clear that there&#x27;s not going to be a common understanding, let alone standard for it. As a freelancer having worked on maintaining many &quot;REST&quot; trainwrecks, I can tell you that naive REST spaghetti is absolutely much worse than any SOA design ever was. The technical debt and high maintenance might not be apparent while you happily code away your new &quot;microservice&quot;; but I can assure you you&#x27;ve just traded a tiny bit of upfront design for a long-term puzzle you&#x27;re leaving behind.<p>Did you know WSDL has supported &quot;REST&quot;-like encoding of parameters in URLs and operations as HTTP verbs since 2001?

This looks a lot like OData - a REST-ful API standard with schema introspection, patterns for defining and traversing resource relationships, well-defined guidance around mechanics, tooling support. In particular, the &quot;Microtypes&quot; concept resembles how entities work in OData - rich query support for collections (eg. sorts, filters, order by), &quot;expansions&quot; on related resources, even inheritance semantics (ie. being able to request a derived entity as its parent type).

I never understood why people love REST. Just use some kind of JSON-RPC, or something like that. In my experience most of so-called &quot;REST&quot; interfaces are just poorly written RPC. Some people even think that REST means HTTP + JSON. It&#x27;s extremely rare to encounter a true REST interface with e.g. HATEOAS, proper caching, etc. And if many developers can&#x27;t utilize technology, probably technology is not good enough to be commonly used. Web Services with their WSDL were the best thing. They were too complex, they use XML which is apparently out of fashion today, but the idea was solid, we just need something simpler but with good enough tooling.

Generally speaking, I think a lot of developers get into trouble by not really putting the effort into grasping the <i>ideology</i> of architectural frameworks like REST, 12factor, and React.<p>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 &#x2F;cars&#x2F;1&#x2F;prices, which I didn&#x27;t like because I feel it breaks REST. There&#x27;s no price model to the car, prices are fields of cars, at least for now.<p>I had to think for a few seconds before coming up with just using a query parameter to set which view to serve, &#x2F;cars&#x2F;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.<p>Coders seem to not want to bother learning how existing solutions are <i>supposed</i> 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.<p>But it&#x27;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&#x27;t then your React applications will be just as horrendous as your jQuery ones were.

REST allows for clients and servers to evolve independently. If you can constrain that you can probably design something significantly simpler. That’s not a shortcoming of REST, though. The channel between your mobile client and your backend would probably be better served with something more like RPC than academic REST.

Kudos to the author for going the extra length of trying to maintain semantic interoperability and reuse by showing how to be backwards compatible with e.g. JSON-LD. This makes it possible to continue to build upon all the vocabularies already created.

Hi, author here. AMA. But I would like to make a couple of points.<p>For starters, a lot of people are looking for a TL;DR. There is no such thing. Same with tooling.<p>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.<p>GraphQL for instance, uses HTTP just for the transport layer. That&#x27;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.<p>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&#x27;t really seen any other document&#x2F;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.<p>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&#x27;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.<p>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).

TLDR?

ok I think I&#x27;m missing something here

I wasn&#x27;t able to read this entirely it&#x27;s a very dense spec.<p>That said , even if the arguments in this spec are solid the entire industry are sold itself to GraphQL.<p>GraphQL has won and it won&#x27;t change.