Industry Standards For Decoupling Front-end & Back-end

[API Dev]

Hi,

I am trying to look for industry standards and best practices for designing our enterprise application so as to decouple the front-end (UI, mobile apps and other interfaces) with the back-end. So far I am come across GraphQL & REST API's (with hypermedia). I see strong advantages of graphql given that it has a stricter type system as compared to REST standards. This makes it easy to roll out within a team of 70+ developers working on multiple features. I do understand the limitations of GraphQL in terms of caching and api discover-ability but I see some work around available in the graphql space.

1. Are there any OTHER industry best practices to this design problem? 

2. What are the cases in which one would use REST API's instead of graphQL for internal api's?

Thanks.

[Michael Tiller]

I don't have any more standards to add, but I have an observation to make about this comparison.

I checked out the limitations you mentioned.  If you look at the synopsis of the differences, I would argue that every advantage they attribute to GraphQL can be done in with hypermedia APIs in a pretty straightforward way.  For example, this "fewer hops" thing is addressed in both HAL and Siren (and other) formats using embedded resources.  In my own APIs, I already have a query language that traverses resources server side and builds up a single response (leveraging embedded resources).  Via profiles, you can advertise not just the response itself, but schemas associated with the responses (and I guess that gives you WYSIWYG...although I'm not even sure what that means in this context).

However, while hypermedia APIs can have many of the benefits of GraphQL you don't get the reverse at the moment.  GraphQL really does not lend itself to caching.  Maybe if you have only whitelisted queries, you could use something like a memcache to store responses.  But it still won't play nicely with a reverse proxy cache.  So your server will still have to respond to every single request. There is client side caching, but that is a bit of a nightmare since there is no mechanism (that I'm aware of) for specifying expiration times, ETags, invalidation, etc. As a result, I think the client side stuff will be overly optimistic.  GraphQL is kind of discoverable, but I'm not sure how you'd reference things that weren't part of that particular GraphQL server (i.e., there is no equivalent of a URL to point to things).

BTW, one of my pet peeves these days is the claim that GraphQL has a type system or is statically typed.  It isn't statically typed if the type checking is at runtime.  Some of the tooling out there is allowing for static checks in the IDE, but I don't think of that as the same.  For sure it allows you to define schemas and that is useful (in some cases, but not in all).  But the tooling to, for example, translate GraphQL schemas back and forth to native type definitions (e.g., TypeScript definitions) is typically one-way at best.

Clearly, GraphQL is the new hotness.  I know it probably sounds like I'm raining on the parade here, but really I'm just trying to be objective about all this.  I would say that GraphQL's popularity is less to do with its technical merits and much more to do with the fact that Facebook is behind it and that the *tooling* is really impressive.  There are a lot of companies founded just on providing the tooling and frameworks alone.  In that sense, it is really a shame that the hypermedia community doesn't have a better story around tooling (or perhaps more marketing around existing tooling).  I was quite interested in the tooling side of GraphQL but the issues around caching and having to effectively restate all my "types" as schemas was not much fun.

Of course, I welcome differing opinions.

--

Mike

ᐧ

[Marsh Gardiner]

Mike makse some solid points. I'll risk the ire of this group by asking what's so bad about coupling front and back ends? In theory, HATEOAS seems like it can power "unbreakable" APIs, but it seems to me like it just pushes the coupling to the application layer (i.e., you have to deal with representing that data somehow). Maybe supporting the "optional" code-on-demand constraint can help you get out of that hole? But then again, it seems like that requires the provider to take on the burden of the experience as well as the underlying service itself. Frankly, I think being unfashionable is a feature and will happily leave the fashion-party to the JavaScript framework ppl. :)

To me, coupling means contract-based (like an OpenAPI spec), and I like that declarative approach. For one, a contract is easy for providers and consumers to understand what they're giving/getting. It's eminently testable. It works pretty well for generating SDKs, especially for statically typed languages. It has great available tooling.

So my question to the OP would be, "What is the specific problem you're trying to solve by decoupling and is that the best use of your company's resources?"

[Andrew B]

Heresy :)

The bit that seems to get overlooked when talking about HATEOAS is that as the developer proving the APIs (i.e. not a client consuming them) you still likely need a spec/contract internally, unless of course your developers make it up as they go along.

So sometimes the decision is more like "shall we keep our specs secret, to force the client to make use of our HATEOAS goodness?". To which the answer might be... why would you conceal such useful information?

[API Dev]

Thanks for the replies. Much appreciated. I have a few comments below

However, while hypermedia APIs can have many of the benefits of GraphQL you don't get the reverse at the moment. 

I understand the graphql disadvantages that you tried highlighting namely caching and the learning curve involved. In fact I would also have to think about authentication too. I get this point but I do not see them affecting us a lot. Talking about caching we don't have any client caching enabled right now too so we might be ok without it too in future. About the learning curve in defining types and schema, I think rolling out REST with hypermedia and explaining the best practices/REST standards (more details below) to a team of 70+ developers would be more difficult than letting them know GraphQL. I would be glad to hear out comments or more thoughts on this.

 

What is the specific problem you're trying to solve by decoupling and is that the best use of your company's resources?

By decoupling the front-end with the back-end, we will allow multiple interfaces that can access data including mobile apps, conversational interfaces like chatbots etc. Along side also keeping the possibility of making this data available for partners too in future.

We are also trying to bring standardization, better documentation and testability to the way our UI accesses the back-end right now. Currently we use java as our backend and react.js for the front-end. We have a monolithic web application deployed on a java ee based application server (no microservices). Right now the front-end code fetches data from backend through REST api's (no hypermedia). The issue is there is no standardization in the REST api's implemented by various teams on different features. Also the api's are very specific to the UI navigation. If we were to build mobile apps that have different UI navigation we would end up in creating new REST endpoints.

With GraphQL I see that different teams would have to define types and query roots for the data models of the respective features. This way there is one standard being followed by multiple teams. With REST, the current api's are not  following REST guidelines/best-practices. Talking about couple of problems to highlight the issue - The REST api url structure is not well defined. The api's are not resource oriented etc.

I am not being biased towards GraphQL but trying to figure out an approach that would best suit us. This design problem also doesn't seem specific to us or a given domain.

Thanks.

[Eric Johnson]

On Wednesday, November 15, 2017 at 9:41:32 PM UTC-8, API Dev wrote:

Hi,

I am trying to look for industry standards and best practices for designing our enterprise application so as to decouple the front-end (UI, mobile apps and other interfaces) with the back-end. So far I am come across GraphQL & REST API's (with hypermedia). I see strong advantages of graphql given that it has a stricter type system as compared to REST standards.

REST is an architectural style. GraphQL is a specific technology and an implementation design pattern. This is not a comparison of the same thing. If it isn't clear what I mean:

• REST-style supports multiple kinds of data - pictures, movies, audio, plain text, JSON, RDF, XML, HTML, etc, whereas GraphQL is about querying APIs
• REST-style explicitly supports caching and massive scaling, whereas GraphQL design hinders caching and gets in the way of massive scaling
• REST-style supports compatibility with older clients in a variety of ways (new URLs for the same service, different MIME types, lenient enforcement of data types such as JSON with extra data), whereas GraphQL supports a specific pattern for compatibility.

GraphQL seems like a perfectly fine piece of a REST-style architecture. But it is only a piece of an implementation puzzle.

 

This makes it easy to roll out within a team of 70+ developers working on multiple features.

That makes sense. REST is an architectural style. GraphQL is a design pattern. REST needs to be mapped onto specific design patterns appropriate for the problem, whereas GraphQL is a design pattern. So it is clearly easier to start working with design patterns directly, rather than figure out the design patterns needed.

REST also is explicitly decoupled from the underlying database design, whereas anything that supports a query language on the front end risks coupling the clients to the underlying structure of the database on the back-end, and decoupling that will be extremely difficult, should it ever be necessary to do that.

 

I do understand the limitations of GraphQL in terms of caching and api discover-ability but I see some work around available in the graphql space.

Among the troubles with treating everything as a GraphQL problem, is that clients can perform what turn out to be expensive queries in the GraphQL space, and it can be difficult to get a server and client to scale to handle the new problem. Whereas, stepping outside of GraphQL, with a RESTful design, the implementation can simply define a new "resource" with a new URL, strip out all the parts of the query that are unnecessary to the new use-case that slow the original query down, and improve the performance.

Relying on GraphQL to "decouple" client and server seems like a work-around for client and server implementors not talking with each other about the problem domain. What you might end up with won't be well tuned to the actual use-cases of the users. This will manifest in myriad small (and possibly big) ways, such as extra clicks to accomplish tasks, slower performance, longer cycles between releases, and even confusing terminology.

 

1. Are there any OTHER industry best practices to this design problem? 

It isn't just one design problem, but multiple problems rolled up in one.

• Data exchange models:
• XML with schema (although perhaps not XML Schema, but RelaxNG instead)
• JSON with schema
• new MIME types (see Atom specification)
• RDF with OWL2
• HTML with RDFa
• API conventions
• OpenAPI (aka Swagger)
• HAL
• Siren
• OData
• GraphQL
• ...
• Query conventions
• OData
• GraphQL
• Sparql
• ...
• Backend data services
• SQL databases
• NoSQL databases
• Caching
• ...
• Usage patterns
• Complex - "single-page" Javascript implementations in the browser
• Multi-page web applications
• Native (mobile) applications
• API-based interactions
• ...

So, yes, saying "REST" is harder, because it requires looking at all of the above problems, and coming to a conclusion about a direction to take. Another challenge with REST is that we typically implement it over HTTP, which is a powerful protocol that's easy to abuse in non-RESTful ways. (For example, the universe of SOAP APIs). It is difficult to tell people not to abuse HTTP and violate the RESTful architectural style, because the problem won't be obvious until a lot of code has been written.

However, in spite of all that discussion of REST, the best kind of project is one that works. So if GraphQL fits your early needs, start with that, but think more broadly about the problem, and don't think GraphQL solves it all. Agile development repeatedly shows us that getting something working, and testing it with real customers works a whole lot better than big up-front design. You're better off picking a direction to start, knowing that you'll change directions, rather than trying to guess in advance.

2. What are the cases in which one would use REST API's instead of graphQL for internal api's?

Perhaps belaboring the point, but REST APIs is really a short-hand for RESTful-style APIs, and encompasses a wide variety of options that don't involve arbitrary queries of data.

Good luck!

Eric.