GraphQL: A legit reason to use it.

I absolutely love ReactJS. Everytime there is new technology that integrates nicely with the ReactJS ecosystem, I write a quick prototype app or create a new branch on an existing app to see what the hype is all about … and if I like it.

I hear and I forget, I see and I remember, I do and I understand.

Continue reading only if you care about the following:

• You care about your users data plan
• You want users to get the data quicker
• You want your developers to do less work and have a better a “Developer Experience” #DX

Did I get your attention?

GraphQL is another middleware layer between your client and your data. It allows your developers to get only the data they need and not over-fetch. Also, it can prevent developers from making extra API calls because they under-fetched. For my last point, it allows developers to do less work by not having to do data manipulation; declare the data you want and then use it. There are many more reasons why GraphQL is awesome but I’ll stick to these in this post.

When developers work with API data, they possibly do the following:

• Go the website, read the API documentation, and see if they have a page where you can make sample queries and get sample results
• Or make a call from your application and either console.log the results or them write to the page to view.

I had to do both of the above and make a GraphQL server to output most of the possible results from their API. Here is a sample query of all of the fields for the query I setup on the GraphQL server.

query {
 weatherForecast(city:”San Francisco”) {
   city {
     id,
     population,
     name,
     country,
     coord{
       lon,
       lat
     } 
   },
   cnt,
   message,
   list{
     dt,
     dt_txt
     main {
       temp,
       temp_min,
       temp_max,
       pressure,
       sea_level,
       grnd_level,
       humidity,
       temp_kf,
       temp_f,
       temp_c
     },    
     temp_f_avg,
     pressure_avg,
     humidity_avg,
     weather {
       id,
       main,
       description,
       icon
     },
     wind{
       speed,
       deg
     },
     clouds{
       all
     }
    }
  }
}

If you noticed, that looks like JSON without the values and most of us are familiar with this already. That query is only most of the fields available from the API, there is even more but the fields seems to be internal fields not revelevent to weather data. So imagine you would receive even more fields if you make RESTful API calls. However, not all those fields are from the API, I added extra fields and that is a good thing … more on that later.

Now here is the code to get only the data I need for an app I wrote earlier.

query:
{
 weatherForecast(city:”${term}”) {    
   temp_f_avg,
   pressure_avg,
   humidity_avg,
   city {
     id,
     name,
     coord{
       lat,
       lng: lon
     }
   },
   list {
     main {
       temp_f,
       pressure,
       humidity
     }
   }
 }
}

Several things I want to point out.

• My app only receives those fields. It is much less than had I called the data using RESTful API calls.
• I aliased some data fields so the fields map nicely with my prop variable names. That is a bonus so I can use ES6/2015 enhanced object literals :)
• That temp_f is something I added to in my query fields because the data only comes in kelvin, “temp”, and I want to work with fahrenheit.
• The *_avg query fields I added that are average values for historic temp_f, pressure, and humidity data that had to be calculated on the front-end.

This works out great for the users of the app working on mobile and have a limited data plan. Also works out for users with lower internet speeds because the app gets less data so users should get the data faster.

The extra fields I added made the developer do less work by not having to write extra code or helper functions to convert the data. No more need to write code or functions to convert the temperature from kelvin to fahrenheit or averages for temp, humidity, and pressure. The components are now thinner and more data comes in and used as-is as values for props so it can be displayed on the page. That may even be a micro-performance boost since the front-end no longer has to perform those calculations at render time and/or you do not need to import any other libraries like lodash to perform the calculations.

Developers still need to go to a site to see what data they have access to and get sample results. GraphQL has an app for that: GraphiQL. There is no need to update the documentation or website with details on the API call. GraphQL is strongly typed so you have to let the server know what type of data it is getting. You can also configure a lot of things about your query. For example, description of the query, fields, and arguments. Because of this, the server is self-documenting. How many developers love to create and maintain documentation? Here is a screenshot of GraphiQL

Developers can go to the right and see what data is available with an easy to navigate UI. On the left, they can make a query they want and there is type-ahead so you cannot type anything that is not available. This prevents a lot of fustrating errors from typos and fat fingers. Then you can get a sample of the results. If you like what you see in the results, then you can copy and paste that query and use in your app with minimal changes. I feel this is much better as a front end developer to work with when compared to using RESTful APIs. The best part, all this came for free! I didn’t have to create or maintain this GraphiQL site. Any change I make on the GraphQL server show up here. How awesome is that!?

Here are some of my pros and cons based on my experience.

Pros:

• DX is great. Working with GraphiQL first blew me away. I wrote the app both ways and wondered where was this all my life.
• I know what the data will look like when I get it.

Cons:

• Setting up GraphQL and configuring it is a lot of work and typing.
• *The code and functions still need to be created and they are just move from the front-end to the back-end. That really isn’t a con if you want DX to improve and keep your front-end code thinner.
• Would possibly require another person on the team.

For the con, it is worth it to me in my opinion. Overall, it is a huge net positive.

There is so much more I can write about GraphQL but I’ll save that for a part II in the future. Next post may be about making mutations on data. Stay tuned.

Conclusion: After writing serveral apps using GraphQL, I can say …. I like it, a lot.

Here is a link to the GitHub repo with the weather app if you want to view the code. It is a weather app written in ReactJS and uses Redux. GraphQL-Weather-App. To run it you will need an api key from openweathermap.org

If you want to learn more about all that is React and you live in the San Francisco Bay Area, then I suggest you go to this Meetup: ReactJS San Francisco. After I go here, I end up writing or enhancing a prototype app (and I’m so stuffed from all the free food). I got so inspired that I am a co-orgainizer of this meetup : Declarative Programmers and we have a event on Saturday, January 23 with a FREE workshop on ReactJS and GraphQL.

Hope you found my post informative and agree that GraphQL is legit.