Why you don’t need a framework to access GraphQL endpoints (Scala edition)

What is GraphQL?

GraphQL is a data query and manipulation language that was created by Facebook in 2012. It’s often hyped as a replacement for REST. It’s not. Really, it’s more of a web-friendly SQL.

The essence of a GraphQL request is super-simple. You send a post request with a query in the body and the GraphQL server responds with the the results of your query as JSON. There are a few things that can trip you up, but once you are aware of them, you can easily make GraphQL calls without using any special frameworks.

Example GraphQL Request/Response

Anatomy of a GraphQL Request

A GraphQL query string has a simple but odd syntax. Here’s an example from my work, it queries for event tracks produced by machine-learning generated classifications.

query {
  tracks(
    where:{
      videoReferenceUuid:{
        equals:"e689d163-3753-4892-9955-a30f99f19684"
      }
    }
  ) {
    id
    maxSurpriseId
    videoReferenceUuid
    varsConcept
    predictedVarsConcept
    events {
      id
      uuid
      x
      y
      width
      height
      time
    }
  }
}

Before you send that in your the body of an HTTP POST request, it needs to be converted to JSON. The steps to do that are:
1. Strip out all the line feeds from your GraphQL query.
2. Escape the double quotes so that "becomes \".
3. Build JSON like {"query": "<insert your graphql here>"}

So for example the above query would be come:

{"query": "query {  tracks(    where:{      videoReferenceUuid:{        equals:\"e689d163-3753-4892-9955-a30f99f19684\"      }    }  ) {    id    maxSurpriseId    videoReferenceUuid    varsConcept    predictedVarsConcept    events {      id      uuid      x      y      width      height      time    }  }}      "}

Parsing a GraphQL Response

When you make a GraphQL query, the response will have your data nested under a data field inside the JSON. In the above query, I requested tracksso the response has a tracks field under data. If you request foo in your query then there will be a foo field under data. The GraphQL response for my query will be something like:

{
  "data": {
    "tracks": [
      {
        "id": 26,
        "maxSurpriseId": 1386,
        "videoReferenceUuid": "21d00e55-...",
        "varsConcept": "Unknown",
        "predictedVarsConcept": "Chionoecetes tanneri",
        "events": [ ... ]
       }
     ]
   }
}

When parsing the response, be sure to walk the JSON tree down through data > <my_object_name> .

Example in Scala

For reference, I’ve included some Scala code that I use for calling GraphQL.

The first class is GraphQL.scala. It hides the boiler plate details of formatting the GraphQL query as JSON, sending the POST request (using OkHttp), and converting the responses JSON to Scala case class (using Circe). As a user the only method I care about in it is queryToFuture

The second class, TrackService.scala, shows an example using GraphQL.scala. I’ve omitted the case classes and circe codecs from brevity. Note at line 43, that I’ve passed List("data", "tracks") as a parameter. As mentioned in the “Parsing a GraphQL Response” section above, this is the JSON path to walk to get to the actual data I care about in the response.