Idea behind GraphQL

The idea behind GraphQL is to introduce super flexible way of fetching (and modifying) data.

How does API look like?

The API looks more like a schema. For example:

type User {
    id: ID!
    name: String!
    email: String!
    age: Int!
  }

  type Query {
    users: [User]
    user(id: ID!): User
  }

  type Mutation {
    addUser(name: String!, email: String!, age: Int!): User
  }

How do I query/mutate data?

You can take what you need (no need for taking full users data):

query {
  users {
    id
    name
  }
}

You can query a specific user:

query {
  user(id: "1") {
    id
    name
    email
  }
}

You can add a user:

mutation {
  addUser(name: "Charlie", email: "charlie@example.com", age: 28) {
    id
    name
    email
    age
  }
}

How does it work under the hood?

For each separate field there must be a specific fetcher (because a client can ask for any configuration of fields). It introduces an overhead and is less performant than traditional REST.

Worth a look

1. https://graphql.org/