Archives
The Programmer's
Hangout
what is ansiblewhat is clojurewhat is denowhat is discordjswhat is dockerwhat is elixirwhat is emacswhat is googlewhat is graphqlwhat is haskellwhat is juliawhat is kotlinwhat is lispwhat is rediswhat is rustwhat is sqlitewhat is sveltewhat is symfonywhat is vimwhat is wslwhat is zsh
Switch to light mode
home
archives
what is graphql

what is graphql

veksen#1060
July 18, 2018
2 minutes read time

What is GraphQL?

GraphQL is a query language for APIs, meant to challenge and replace REST. At its core, GraphQL enables declarative data fetching where a client can specify exactly what data it needs from an API. Put bluntly, a lot of people claim GraphQL to be REST 2.0.

Why does GraphQL exist?

GraphQL was created internally by Facebook in 2012, mainly to optimize the network load for mobile devices. Interestingly, other companies like Netflix or Coursera were working on comparable ideas to make API interactions more efficient. When Facebook announced GraphQL, Coursera abandoned their efforts and jumped on GraphQL.

What makes GraphQL better than REST?

  1. GraphQL resolves the issues of underfetching, and overfetching of REST. For example, if you were to retrieve a user, its name, and the title of his posts, REST would end up over and under fetching this :
/users/5
/users/5/posts

// REST return for endpoint /users/5
{
  id: 5,
  name: "veksen",
  email: "veksen@tph.com",
  role: "Chat Mod",
  permissions: ["readThis", "writeThat"],
  dob: "1970/01/01",
  location: "Montreal"
}

// REST return for endpoint /users/5/posts
[
  { id: 3, title: "My first post", content: "The full content of the post, possibly a few Ks of data" },
  { id: 7, title: "GraphQL is pretty neat", content: "The full content of the post, possibly a few Ks of data" },
  { id: 8, title: "GOTO considered harmful", content: "The full content of the post, possibly a few Ks of data" }
]

Meanwhile, a GraphQL query would look like :

query user(id: "5") {
  id
  name
  posts {
    id
    title
  }
}

// GraphQL return for our query
{
  id: 5,
  name: "veksen",
  posts: [
    { id: 3, title: "My first post" },
    { id: 7, title: "GraphQL is pretty neat" },
    { id: 8, title: "GOTO considered harmful" }
  ]
}
  1. GraphQL helps building features faster. Because of the way the front-end can explicitly query the data it needs, it's not rare to not need to update the backend API. Again, using the example from earlier, if we wanted to also fetch the user friends, we could simply add it to our query:
query user(id: "5") {
  name
  posts {
    title
  }
  friends {
    firstName
    lastName
  }
}
  1. Strong-typing. Contrary to working with JSON responses limited to string and numeric, and the discrepancy between front-end (JS) and any back-end language being lost in translation.

Core concepts

GraphQL has three types of operations:

  • queries (fetching data),
  • mutations (creating/updating/deleting data),
  • subscriptions (real-time listeners to data changes, using websockets behind the hood).

Basic query:

query User($id: ID) {
  user {
    id
    role
    permissions {
      name
    }
  }
}

Basic mutation:

mutation CreatePost($title: String!, $content: String!, $draft: Boolean!) {
  createPost(title: $title, content: $content, draft: $draft) {
    title
    content
    draft
  }
}

Basic subscription:

subscription OnMessageReceived($conversationId: ID!) {
  messageReceived(conversationId: $conversationId) {
    id
    content
  }
}

At its core, GraphQL consists of two parts: client, and server.

A server contains a single endpoint, accepting GET and POST requests, which are translated like so:

{
  me {
    name
  }
}

becoming:

http://myapi/graphql?query={me{name}}

How can I start using GraphQL?

While it is possible to convert an existing REST endpoint to GraphQL, either through automated tools, or manually, the best case scenario would be on an entirely new project.

Common misconceptions

  • Because the query is explicit, a lot of people think that GraphQL is unsafe, making all of the data available to anyone. GraphQL is bound to the same safety procedures that a regular API would: permissions are defined by the backend.

  • GraphQL is a query language for APIs, not databases! This means it can be used with any database. The API is responsible for converting the query to a database query.

  • When it was first announced by Facebook, a lot of people thought it was React exclusive! This is not true. GraphQL can work on any tech stack (although some languages have more complete tooling than others)

Closing notes

Today, GraphQL is used in production by lots of different companies such as GitHub, Twitter, Yelp and Shopify - to name only a few. We are seeing month after month, small and large companies converting to it.

Attached resources

Example codebase