Comments on GraphQL

Written on December 1, 2017
[ graphql  facebook-graph  wwe  ]

At work, I’m been diving deep on everything and anything Facebook:

  • What is the Open Graph Protocol?
  • How do I use the Graph API?
  • What data can we get from Facebook Insights or Analytics?
  • How about Audience Insights? Automated Insights? Facebook IQ?

The list goes on!

Today I touched on GraphQL. Figured I’d take some notes and blogify them for future reference.

What is GraphQL?

GraphQL is an API standard invented at Facebook in 2012, and open-sourced in 2015. It is an alternative to the REST standard.

Something I thought was interesting is that a GraphQL server exposes only a single endpoint, instead of multiple endpoints that return fixed data structures. Given the single endpoint, the client can request that data structure needed for a given situation. This simplifies things! (More on this kind of stuff in next section.)

Riveting Tidbit: At the time of this writing, the Facebook Graph API is a REST API, not GraphQL! However, you can use GraphQL-like syntax when querying. From the Graph API Docs:

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

Why use GraphQL?

Also – Why try to reinvent the explanation?

From graphql.org:

  • Ask for what you need, get exactly that: Send a GraphQL query to your API and get exactly what you need, nothing more and nothing less. GraphQL queries always return predictable results. Apps using GraphQL are fast and stable because they control the data they get, not the server.
  • Get many resources in a single request: GraphQL queries access not just the properties of one resource but also smoothly follow references between them. While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data your app needs in a single request. Apps using GraphQL can be quick even on slow mobile network connections.
  • Describe what’s possible with a type system: GraphQL APIs are organized in terms of types and fields, not endpoints. Access the full capabilities of your data from a single endpoint. GraphQL uses types to ensure Apps only ask for what’s possible and provide clear and helpful errors. Apps can use types to avoid writing manual parsing code.

Or, as Samer Buna deftly explains it at FreeCodeCamp:

The 3 most important problems that GraphQL solves beautifully are:

  1. The need to do multiple round trips to fetch data required by a view: With GraphQL, you can always fetch all the initial data required by a view with a single round-trip to the server. To do the same with a REST API, we need to introduce unstructured parameters and conditions that are hard to manage and scale.
  2. Clients dependency on servers: With GraphQL, the client speaks a request language which: 1) eliminates the need for the server to hardcode the shape or size of the data, and 2) decouples clients from servers. This means we can maintain and improve clients separately from servers.
  3. The bad front-end developer experience: With GraphQL, developers express the data requirements of their user interfaces using a declarative language. They express what they need, not how to make it available. There is a tight relationship between what data is needed by the UI and the way a developer can express a description of that data in GraphQL .

Exploring GraphQL on GitHub using GraphiQL

Facebook’s Graph API explorer has been helpful with getting up-and-running in previous posts. Similarly, I have found Github’s GraphQL explorer, GraphiQL,to help get my bearings.

Recycle, Reduce, Reuse

How many times have you written the same line of code or SQL query? Often we like to minimize such redundancy (e.g., with functions or, in SQL, with views). This type of philosophy remains true when issuing graph queries!

In GraphQL, we call a reusable chunk of code a “fragment”. Fragments are reusable graph (sub)queries. They are important for our sanity, e.g., in reducing the size and apparent complexity of a query.

For example, below a fragment is used to simplify a query requesting the same data from mutiple repositories.

fragment repoFrag on Repository {
  id
  name
  description
}

query myRepos { 
  blog: repository(name: "krbnite.github.io", owner: "krbnite") {
    ...repoFrag
  }  
  deepL: repository(name: "deep-learning-nanodegree", owner:"krbnite") {
    ...repoFrag
  }
  mushrooms: repository(name: "FungusAmongus", owner: "krbnite") {
    ...repoFrag
  }
}

References & Further Reading