Creating GraphQl API with Sangria

Sangria is a library that processes the graphQL queries coming to the server and pass on the object to business layer of the application, which mostly further queries database to get information which sangria passes on as response to the query. GraphQL is a query language for the servers with which only one route can be used to give response to any query, which are defined by our GraphQL schema, if you’re more interested in knowing about the GraphQL then you can go to graphql.org/learn, it’s really good documentation that explains GraphQL very well.

For the explanation, let’s assume our only route is /graphql. And we are going to receive our requests on that route. All the requests, either it’s to get some data, update, create or delete the data everything is send to server in POST data. The sangria query should have three fields in the post data.

{
    "query" : "",
    "variables" : "",
    "operations" : ""
}

It’s indeed the JSON data. This JSON data wraps the GraphQL query in it. Though Sangria doesn’t care whether the query data is wrapped in JSON, it only expects the strings of query, variables and operations. Query is a required string while variables and operations are optional, depending on the query.

According to graphql specification, we need to create a schema, against which server process our qraphql queries.

With Sangria, we can define any kind of schema element defined in the official specification of the GraphQL by Facebook, interface, union type, enum type, object, list, scalars etc. After the types are defined the queries, mutations and subscriptions are defined and those three are included in the Schema() object against which queries are processed.

When the graphql query arrives at server, it’s parsed by the QueryParser object’s parse() method.

QueryParser.parse(query) match {
  // query parsed successfully, time to execute it!
  case Success(queryAst) ⇒ //pass queryAst to query executor along
                          //with variables and operations if any
  case Failure(error: SyntaxError) ⇒ //Send back the parsing error message
}

Once query is parsed, it is passed on to the executor to execute that query.

Executor.execute(SchemaDefinition.schema, query, new ProductRepo,
 operationName = op, variables = vars)

The execute method takes Schema object, the parsed query,  the repo/context object, operations, variables, exception handler among others.  Repo object is an instance of class that defines the methods to handle mutation, query or subscription defined in the Sangria schema.

Once the business layer processes the required query and give data back to API layer Sangria forwards the message back to the client. The more help can be found on sangria’s website and also the example repositories of the Sangria.

Currently we’re working with Sangria and Lagom to create the Better APIs.