What is GraphQL?

What is GraphQL?

GraphQL is a query language. A query language specifies procedures for retrieving data from a database. If you've used SQL then you've used a query language before...

You run GraphQL queries against a GraphQL server just like you'd run SQL queries against a SQL server.

GraphQL servers are implemented in different languages. Just like you can create a REST server using Java or JavaScript, you can create a GraphQL server using Java or JavaScript.

What is GraphQL used for?

GraphQL is used for requesting data from a server. GraphQL is used as a more optimal alternative to REST.

Using GraphQL, clients can directly query a server for the exact information they need. They don't have to worry about specific REST endpoints for retrieving data. Instead, they submit queries based on a predefined schema like this:

type User {
  id: ID!,
  username: String,
  email: String
}
type Query {
  users(count: Int):[User]
  user(id: ID):User
}

Any type of application can benefit from GraphQL. A React or Angular UI can more precisely query data without having to worry about endpoints.

This reduces the repetitive implementation of RESTful endpoints and gives calling applications more control.

How does GraphQL work?

A GraphQL query is a collection of fields:

query {
  users(count: 1)
  {
    id,
    username
  }
}

These fields correspond to a schema defined by types:

type User {
  id: ID!
  username: String
  email: String!
}
type Query {
  users(count: Int):[User]
  user(id: ID):User
}

Object types represent the objects you can fetch from your service. The User is an object type.

Query types defines queries that can be called by the client. Notice how the query "implements" the users(count: Int):[User] defined in the Query type.

Queries are run against a GraphQL server. The server can be implemented just like a REST server can. Different languages have different implementations that do the same thing.

After parsing the query, the server runs a resolver function for each field. These resolver functions can be optionally implemented to make async calls to a database or simply return field values.

After "resolving" each field in the query, the server returns a response object with the same structure as the query:

{
  "data": {
    "users": [
      {
        "id": "1",
        "username": "superuser"
      }
    ]
  }
}

This gives back the client the exact structure they asked for. This presents some key advantages over REST...

GraphQL vs REST

GraphQL solves the over/under fetching problem with REST. While REST services dictate what endpoints return what data, GraphQL gives calling applications the power.

GraphQL solves the over/under fetching issue with REST. The query language gives calling applications full control over what data is returned.

Looking for more? Check out GraphQL vs REST.

Problems with GraphQL

Caching

Caching can be difficult with GraphQL. While solutions do exist, caching is inherently easier with REST. You can set specific caching rules on specific endpoints. You can cache URLs in a browser.

GraphQL typically works over a single endpoint making it more difficult to cache resources so easily. It can be done but it's more complicated using GraphQL.

New problems replacing old problems

GraphQL puts a lot more control in the client's hands. This doesn't necessarily make the client's job easier. As a GraphQL schema grows so do the headaches of constructing query payloads.

Conclusion

GraphQL is impressive and trending strongly. While it offers some clear advantages over traditional REST, it shouldn't be looked at as BETTER necessarily.

GraphQL is a trade off with REST. GraphQL is not an improvement to REST. Use GraphQL if you want to give calling applications declarative control over the data they request.

Your thoughts?