Adopt GraphQL: Implementing GraphQL Schema In The Browser
You probably keep on hearing about GraphQL from various sources on the Internet. It’s hard not to. GraphQL is a specification for building and consuming APIs, it is proposed and open-sourced by Facebook and people say, it is a good alternative to the REST approach.
I won’t be selling you on GraphQL today, people did a great job with that before me, so for this article I assume that you are a frontend developer that is already interested in the technology and looking for a way to start using it in your organization.
How to adopt GraphQL?
I can definitely say, that until your company is just two people — you and your manager, approaching him with crazy fire in your eyes and saying: “Hey boss, I need two backend developers, an ops engineer, a couple of Android and iOS devs, and we’ll rewrite our stack to GraphQL, it’s gonna be AWESOME!” won’t help you in achieving this goal. You have to learn how to do it gradually, without nuking the world around you. Let’s take a look what Facebook engineers say about it:
“So, I can use GraphQL on the client without implementing it on the backend?” — you ask. Yes, you can! We at Showmax have been doing it for quite a while now.
Our motivation for adopting GraphQL
We are using React as a view framework and we really like its component model that provides just the right amount of encapsulation so that while working on a particular part of the app we don’t have to keep the entire application in our brain’s RAM. Moreover we extend the “component” approach to our CSS styling solution — we use JSS to co-locate the components and their corresponding CSS styles while eliminating the problem of CSS class names clashes. So when we first heard of GraphQL we immediately recognized an opportunity to extend the “co-location” approach even further by keeping the GraphQL queries/fragments close to the components that use them:
The example above uses Apollo GraphQL Client and its React integration. Besides the query co-location, by utilizing the power of GraphQL, ApolloClient provides some other cool features to your frontend app for free:
- Normalized model caching
- Optimistic UI updates
- Data resolving during server-side rendering
- Auto-polling
- Realtime subscriptions
Considering all this, we decided that we want to use GraphQL for our React app, but of course we didn’t have a GraphQL backend. So we started developing our GraphQL schema as a separate package that we were going to use in the client app as a data fetching layer.
Client-side GraphQL schema
One of the greatest traits of GraphQL is that it doesn’t dictate you which protocol of communication to use or how to resolve data in your schema. In other words, you don’t have to send your queries over HTTP and/or retrieve data for a response from a database. This is how your schema can look like if you want to use it from the browser:
In the root Query definition we declared one field — movieById — of type Movie . The trick that allows us to use this schema in the browser is in resolve method. This method is used by GraphQL executor to resolve data for a query in runtime. Because, as I mentioned above, there are no limitations on how you can implement it, you can use browser’s fetch API to resolve data from your existing REST backend service.
All that is left to do to complete the integration for the app is to configure your GraphQL client library of choice to use locally imported schema instead of calling an HTTP /graphql endpoint. This is how such a configuration looks for ApolloClient:
It is just a matter of providing an instance of SchemaLink from apollo-link-schema package to the constructor of ApolloClient, passing your “local” schema to it and you can start leveraging the awesome API that GraphQL and Apollo provide in your application.
Below, we use the movieById query that we defined on one of the previous steps to fetch Movie data in our MovieDetailPage component. The result is declarative and easily readable! Moreover, you can use GraphQL query to generate propTypes for your components, specify different fetch policies which define how cache is used in resolving data, enable auto-polling for a query and so much more.
Next steps…
The approach we described allows you to evaluate how you can develop a client application with GraphQL API without touching a single line of backend code and affecting other teams.
That being said, this setup still does not leverage all the strong sides of the technology: dealing with over-fetching and avoiding multiple network roundtrips when fetching the entire data set for a particular view. But you can easily include these features on your next steps of GraphQL adoption. So where can you go from this point? The immediate thing you can do next is to take the schema you were using on the client, add node-fetch polyfill and deploy it to a NodeJS server.
With this simple step not only the over-fetching and multiple roundtrips issues go away, but other client teams like iOS, Android or SmartTV, can start using GraphQL and reaping its benefits.
After this, if all teams in your organization agree that GraphQL is beneficial for them and you would like to go all in for it, you can completely remove your old REST API Gateway and replace it with a GraphQL one, that will directly talk to the individual microservices or databases.
Try it!
GraphQL definitely has some pros and cons but I believe it has a good chance to replace REST as the de facto standard API paradigm. If you are excited about it as much as we at Showmax are, you might want to try to use it in your organization. My main message is — “Don’t be afraid to try”!
GraphQL is designed extremely well, so that it allows teams to gradually adopt it while minimizing the disruption it poses to other colleagues’ work. I hope this article will help you on your way towards building great APIs in a modern way!
If you want to see more, I’ve created a GitHub repo that implements a working example of the client-side GraphQL setup that we discussed in this article. Also I was giving a talk about this topic at the Webexpo conference in Prague in September 2017, please check that video, it has a bit more details covered.
Share your story
Do you use GraphQL in your company? Please share your story of adoption, what insights or lessons you’ve learned.
