Why GraphQL

The past five years have witnessed a momentous shift in how web and mobile applications are designed. Traditional REST APIs are becoming increasingly cumbersome because they are required to support multiple devices with different screen sizes and potential network latency issues. Over fetching and under fetching data are being identified as problematic as optimal user experience is increasingly coming to depend on speed of requests, rather than page render times.

What is GraphQL

The solution to this mismatch between what the server provides through REST endpoints and what the client actually needs is GraphQL. GraphQL is an API query language in which the client makes a request and the structure of the server's response matches the structure of the request. The server defines its capabilities, and the client can request any subset of those capabilities. The result is a flexible system where the data requirements of the client are met with a single response.

GraphQL has the potential to transform how we think about APIs, but the ecosystem is young and examples can be difficult to find. What is needed is a framework that provides structure and reduces the need to write repetitive code, but still allows the developer to have control over their code and the flexibility to extend their GraphQL schema with custom logic.

Allograph

Allograph is a framework for rapidly developing GraphQL servers. Co-created by Ting Chou and Rachel Minto, Allograph provides a flexible and convenient way to create a GraphQL server for your existing or new application, and it was designed to solve the most common problems encountered when creating a GraphQL server.

1. Empty Paper Problem

You've decided to create a GraphQL server. Now what? How will you structure your application? With Allograph you know exactly what code you need to write and where your code should go. We've given you an organized file structure with most of the code already written. All you need to provide is your postgres database credentials and you'll have a server up and running in minutes. From there, you can choose to add custom business logic and extend your server to meet your application requirements.

2. Repetitive Code

Let's face it: GraphQL code can be repetitive. For each of your database tables you'll want to write queries, mutations, types, and models. And a lot of that code will be CRUD. So you can copy and paste and make the slight changes here and there, miss a few changes, debug, and repeat. A simple table with a few columns will be about 140 lines of code and you have to write that code for pretty much every table. Or you can use Allograph to create all of your default mutations, queries, types and models for you.

3. Time Spent Looking for Tools

Developers are excited about GraphQL for good reason, which means that new tools are popping up every day. Some of these tools have been tested and approved, but others have limited documentation and few examples. With Allograph, we've taken the responsibility of curating and provided integration with the tools that will make coding pleasurable. You can use Allograph's toolset for data caching and batching, authentication and authorization, and running migrations.

4. Lack of Examples

GraphQL is a language specification, not a storage engine, so it can be implemented in any language. While www.graphql.org provides good documentation, the examples are written in the GraphQL language, not in the language that you'll be coding in, so the syntax is quite different. We wrote Allograph in JavaScript, and we generate files that you can inspect to see how we write the default queries, mutations, types and models. Those files are a great resource when it comes time to write custom logic.

5. Loosing your REST API

You've spent years creating your REST API and we don't want to see that development time go to waste so Allograph allows for incremental adoption. Provide your REST API as a swagger json file, and Allograph will create default queries for each REST endpoint that are integrated into the GraphQL schema generated from your database. Then as time permits you can identify which REST requests are most expensive and move those over into being fully GraphQL.

Getting started

You can clone Allograph from its Github page.

With a convenient command line interface and the ability to have a server up and running in less than five minutes with all of your defaults automatically generated from your postgres database, Allograph allows you to focus on the custom business logic that makes your application unique. We look forward to hearing your feedback!

Ting Chou and Rachel Minto