Jul 07, 2017

GraphQL: New, shiny and worth the hype!

It’s hard to keep up in the world of software development, especially these days. There’s always some new framework, library, preprocessor, server, language. Knowing which is just noise to be ignored or which is groundbreaking is not a trivial task . Also “noise” is different for everyone depending on the developer you are right now and the one you want to become.

It’s particularly difficult for me, because I’m not just a back-end developer; while I’m trying to decide whether it’s time to learn Kotlin, Elixir/Phoenix hype keeps getting my attention etc.

GraphQL however, is one of those things I think isn’t noise for most developers. Mobile, front-end, back-end, everybody needs to give GraphQL a look.

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

Umm…so, what IS GraphQL?

GraphQL is simply a specification (like all languages) for how clients get data from APIs.

I don’t understand, how is that different from REST?

Well,

With HTTP REST APIs:

  • You make your API respond to specific types of requests ( GET, POST, PUT, DELETE) at specific URLs/endpoints with specific parameters.
  • You document these specific types of requests, their corresponding URLs and parameters so that they be used by the client application.
  • You write code such that your client (iOS, FE web app) makes those specific types of requests, to those specific URLs with those specific parameters to get (or save) data as is needed.

If this were a conversation between client and server, it would go like this:

Server: Yo, if you want the information on users, just shout ‘/USERS’, and I’ll give you a list of them. But if you want to see the products the user has bought, you gotta shout ‘/USER/PRODUCTS’ along with the user’s ID and if you want…etc. Got it?

Client: *in Morty’s voice* Man, that was a lot of things, could you write that down for me? No way I could remember all that.

Server: Sure, the devs have written really nice documentation for you.

With GraphQL APIs:

  • You make your API able to execute and respond to GraphQL queries.
  • You write code such that your client sends GraphQL queries to your server asking for whatever data it wants, however it wants it.

If this were a conversation between client and server, it would go like this:

Server: Just ask for whatever you want, how you want it, in whatever combination you want. As long as you’re speaking in GraphQL queries, I’m your man!

Client: Awesome!

GraphQL is actually almost like defining functions/methods that your client can call. Just a bit more powerful, because the client can determine exactly what it wants returned and can combine some of these functions.

If you’ve ever used SQL, this should have started becoming clear by now. In SQL you write queries to get the data you want from the database, how you want it. The difference here is that:

  • You’re not querying from within the same application, you’re using the client application to query the server application.
  • You get to define what these queries are/can be.

Example

{
  heroes {
    name
  }
}

The above is a simple GraphQL query the client would make if it wanted to get a list of Heroes and their name(s).

{
  heroes {
    name
    powers
  }
}

This is a GraphQL query the client would make if it wanted to get a list of Heroes, their name(s) and powers.

{
  heroes {
    name
    powers
  },  
  villains {
    name
    powers
  }
}

This is a GraphQL query the client would make if it wanted to get a list of Heroes, their name(s),their powers, and a list of Villains, their name(s) and powers.

{
  heroes {
    name
    powers
  },  
  villains {
    name
    powers
    knownCrimes(from: 1982, to: 2017) {
      casualties
    }
  }
}

This is a GraphQL query the client would make if it wanted to get a list of Heroes, their name(s),their powers, and a list of Villains, their name(s) and powers, crimes they’ve committed between 1982 and 2017 with accompanying number of casualties.

The response would be some thing like this:

"data": {
    "heroes": [
        {
            "name": "Spiderman",
            "powers": ["Spider Sense", "Web"]
        },
        {
            "name": "Batman",
            "powers": []
        }
        ...
    ],
    "villains": [
        {
            "name": "Dr Octopus",
            "powers": ["Mechanical Tentacles"],
            "knownCrimes": {
                "casualties": 657
            }
        },
        {
            "name": "Rick Sanchez",
            "powers": ["Portal Gun", "Genius mind"],
            "knownCrimes": {
                "casualties": 999999999999999
            }
        }   
        ...
    ]
}

You get the picture, right?

How to make GraphQL work?

Client Side

Essentially, the client makes POST request to the server’s GraphQL endpoint with the query as the body of the request. Though there’s no need to do this manually each time. There are excellent client side libraries that take away a lot of the doldrum-y parts of making GraphQL requests. My favourite of them is Apollo, which has different libraries for React, ReactNative, Angular, iOS and Android.

Server Side

You can create a GraphQL API in any programming language. Of course, your server-side code needs to be able to parse a GraphQL query, extract arguments and return fields, then respond accordingly.

Thankfully, you don’t have to write these parsers yourself. There are excellent libraries for .NET, Clojure, Elixir, Erlang, Go, Java, JavaScript, PHP, Python, Scala, Ruby.

I have used the Ruby one heavily over the past two weeks and it’s awesome. I plan on writing a follow up post with an example Rails GraphQL API on here and another one with Sails.js on hellosails.com.

You can also get your hands dirty and test out GraphQL on the newly launched Apollo Launchpad. With simple ES6 you can see what it’s like to create a GraphQL server and immediately query it. It does a lot more and this article is a perfect introduction.

Why GraphQL?

  • This is something I didn’t get to, but you’ll see from my next article or from actual usage of GraphQL. It kind of enforces writing documentation as you code, but it doesn’t feel tedious, at least with the graphql-ruby gem. (Almost) automatic documentation is a great thing for both client and server, isn’t it?
  • The client no longer needs to make multiple queries to display data on just one view. With REST, our final query with heroes, villains and knownCrimes would require about 3 calls to the server. With GraphQL, it’s just one query. Also, getting nested results is a breeze, it doesn’t require an extra request or weird &expand=[knownCrimes] url parameters that can get unwieldy quickly.
  • It can be incrementally adopted, you don’t have to switch your entire application to GraphQL. You don’t even have to change your application’s current operation at all, you can just add GraphQL to it, however you want.
  • It’s not tied to any specific language or framework. It’s just a specification. You can use it with whatever data store you like MongoDB, Postgres, anything!
  • There’s probably more but it generally improves organization, communication between developers and stability of code because of it’s simplicity when compared to REST.

That’s all for today! Go forth and GraphQL!

Copied to clipboard!