A sensible approach to GraphQL; a case study

Lambda or `now`, Express or`micro`, Graphiql or GraphiCLI

I was first introduced to GraphQL by creator Dan Schafer at GitHub Universe, but my first time trying it out was for a production ready backend for a client of ours. Down the rabbit hole we go. . .

GraphQL just makes sense. Get only the data you need, when you need it. Getting more data is not really a matter of changing your code, but just the words in your queries, mimicking what human language is really for. Even better, GraphQL forces interfaces in JavaScript for your queries, allowing you to specify which arguments are required and which are optional with theGraphQLNonNull type.

Despite it being virtually brand new, GraphQL comes with some amazing tooling, like Graphiql. The problem with Graphiql, however, is that you can’t send HTTP headers with your requests out of the box, making it difficult to test your app if your schema is protected by Authorization headers. Zeit founder Guillermo Rauch states the importance of this metadata:

In real-world applications the metadata of the request is of particular importance.
The response might vary, for example, according to the capabilities of the client. If the User-Agent is so, or the Accept header is such. These won't be automatically present in your payloads, so you'll have to manually supply them in each function call.

For these same reasons, the team jumped ship from using AWS Lambda and decided to serve our GraphQL with zeit’s now.

Since every query is made with a POST to /, we had objectively created a micro-service, screaming for the use of more zeit open-source software: micro. The start to this server looks dead simple:

`micro` server for `graphql`

and as a result we got the headers we wanted into our GraphQL queries!

This is especially clean with async/await, but in the end we transitioned to using Express for the simple express-graphql middleware and easy plug- ability for handling issues with CORS and redirecting to our Graphiql instance on GET requests.

But maybe I don’t want to go to Graphiql! Our issue of sending headers with requests still remains. The other issue with using Graphiql is that you need to restart your dev server when you update your logic, and if you change your schema your Browser needs to be refreshed for Graphiql to become aware of these changes — causing visual errors that might no longer be present under the hood.

It seemed like the job for a CLI, so I built it: gest(pronounced guest). With gest, sending a query is as simple as gest '{ test }', or gest test.graphql with test.graphql containing your query. To solve the header issue, you can send headers like gest -H Authorization=e124e --baseURL https://test-2ae34342.now.sh '{ test }' . Header flags work for testing your schema directly (without HTTP) too, by passing these header flags into context.

You can also use gest directly in your tests, working alongside another of Facebook’s tools, jest:

testing with `gest` and `jest`

Finally, you can also use gest to send requests with HTTP, testing each now deployment before aliasing to production with --baseURL.

Gest lets you test rapidly in development, run integration/end-to-end tests during staging, and even ping your production API. As a bonus I added helpful flags for testing--all of your *.(query|graphql|gql) files and printing a summary, and --inspect for printing a representation of your schema (all colorized!). Check out the README for other configurations and abilities.

now ,Express, and gest — a sensible stack for building a GraphQL API.

Thanks so much for reading! Find me on GitHub or reach out to me on Twitter: @fixitup2. Would love to chat if you are interested in `gest` or anything else!