GraphQL & Python

7.23.21

I was recently asked to help develop a project and one of the technologies used for the project is GraphQL. GraphQL is something I have read lightly about but never dove in. So I did to familiarize myself with it.

What is GraphQL? “GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.” – graphql.org
So, GraphQL is a query language for APIs, NOT databases. GraphQL claims to be the new API standard, providing a more efficient, powerful and flexible alternative to REST. It was developed and open-sourced by Facebook and is now maintained by a large community of developers. GraphQL enables declarative data fetching where a client can specify exactly what data it needs from an API. Instead of multiple endpoints that return fixed data structures, a GraphQL server only exposes a single endpoint and responds with precisely the data a client asked for.

Since GraphQL is API focused, it is usually thought of as frontend technology but the API is still implemented on the backend (server side). GraphQL servers are available for many languages (Haskell, JavaScript, Perl, Python, Ruby, Java, C++, C#, Scala, Go, Rust, Elixir, Erlang, PHP, R, D and Clojure). I decided to dive in using Python so I could experiment using Django as my framework. Since choosing to work with Python and Django I also utilized Graphene, which is a Python library for building GraphQL schemas/types using a code-first approach. Code-first meaning, instead of coding in GraphQL SDL (Schema Definition Language), you can code in Python. Schema-first would be the contrasting approach (i.e. Apollo for JavaScript and Ariadne for Python). Graphene also has a Django specific module.

A really cool thing about developing a GraphQL backend API is that it allows developers to focus on describing the data available rather than implementing and optimizing specific endpoints. It allows this through a schema and resolve functions. In GraphQL, a Type is an object that may contain multiple fields. Each field is calculated through resolvers, that returns a value. A collection of types is called a schema. The schema is a model of the data that can be fetched through the GraphQL server. It defines what queries clients are allowed to make, what types of data can be fetched from the server, and what the relationships between these types are. The schema tells the server what queries clients are allowed to make, and how different types are related but they do not handle where the data comes from. Enter the resolve functions. Resolve functions specify how the types and fields in the schema are connected to the backend(s). GraphQL resolve functions can contain arbitrary code, which means a GraphQL server can to talk to any kind of backend and any kind of database. Another really cool feature of GraphQL is that no matter how many backends you use, all the client will see is a single GraphQL endpoint with a simple, self-documenting API.
Another big feature of GraphQL is the integrated, interactive in-browser IDE, GraphiQL. See directly below.



GraphiQL provides a a split window interface for queries on the left and results on the right. It also provides a GraphQL documentation search feature. It is also built with React which was not surprising to discover. Above is an example of what a query of the GraphQL server looks like and below is mutating (sending data to) the server.

Those initial links that were queried were originally created with Django. Using Django has other advantages like user authentication. Creating a schema class in Django, you can create users through GraphiQL. Using the django-graphql-jwt library you can implement JWT (JSON) tokens which is the more modern method of authenticating users.


It’s pretty to easy to see why these GraphQL APIs are so popular, especially when thought of in the context of frontend development. Being able to specify exactly what you want out of an API means saving on payload size which means saving on bandwidth which also includes minimizing round trips to the server which means more saving on bandwidth (plus many, many more advantages) which equals GraphQL providing the natural evolution of the REST API.