What is GraphQL?

Overview

GraphQL is a querying language and server-side runtime for application programming interfaces (APIs) that provides a complete and understandable description of an application's data. GraphQL prioritizes giving clients the power to ask for exactly what they request and nothing more.

GraphQL is designed to make APIs fast, flexible, and developer-friendly. It can even be deployed within an integrated development environment (IDE) known as GraphiQL. As an alternative to REST, GraphQL lets developers construct requests that pull data from multiple data sources in a single API call.

Additionally, GraphQL gives API maintainers the flexibility to add or deprecate fields without impacting existing queries. Developers can build APIs with whatever methods they prefer, and the GraphQL specification will ensure they function in predictable ways to clients.

Common Terms

Schema

• A GraphQL schema is at the core of any GraphQL server implementation. It describes the functionality available to the client applications that connect to it. We can use any programming language to create a GraphQL schema and build an interface around it.

Queries

• In the CRUD model, you can think of queries as being the Read operation

Mutations

• In the CRUD model, you can think of mutations as being the Create, Update, Delete operations.

Resolvers

• a collection of functions that generate a response for a GraphQL query. In simple terms, a resolver acts as a GraphQL query handler.

Examples

The best way to get a sense of how GraphQL works for the clients consuming an application via API is to demonstrate in practice.
Take a look at this fictitious query searching for pets:

query {
  pets {
    id
    name 
    petType
  }
}

This will have a response of:

{
  "data": {
    "pets": [
      {
        "id": "1",
        "name": "Spike",
        "petType": "Dog"
      },
      {
        "id": "2",
        "name": "Snowball",
        "petType": "Cat"
      }
    ]
  }
}

Now let's say you want to rename a pet. You can do this using a mutation like this:

mutation { 
  changePetName(input:{
    id: "1",
    new_name: "Rex"    
  })
}

This will update the pet's name from 'Spike' to 'Rex'. Additionally, you can combine both mutation and query and get back the response of the pet's new name all in one command:

mutation { 
  changePetName(input:{
    id: "1",
    new_name: "Rex"    
  }){
    pets{
      id
      name
    }
  }
}

Which will respond:

{
  "data": {
    "pets": [
      {
        "id": "1",
        "name": "Rex",
        "petType": "Dog"
      },
      {
        "id": "2",
        "name": "Snowball",
        "petType": "Cat"
      }
    ]
  }
}

To understand more about query and mutation capabilities, checkout the official documentation regarding them here

Pros and Cons

Thinking about trying GraphQL in a business or enterprise environment? It comes with both pros and cons.

Advantages:

• GraphQL calls are handled in a single round trip.
• Clients get what they request with no over-fetching or under-fetching.
• GraphQL is faster than other communication APIs
• A GraphQL schema sets a single source of truth in a GraphQL application. It offers an organization a way to federate its entire API.
• Strongly defined data types reduce miscommunication between the client and the server.
• GraphQL is introspective. A client can request a list of data types available. This is ideal for auto-generating documentation.
• GraphQL allows an application API to evolve without breaking existing queries.
• Many open source GraphQL extensions are available to offer features not available with REST APIs.
• GraphQL does not dictate a specific application architecture. It can be introduced on top of an existing REST API and can work with existing API management tools.

Disadvantages:

• GraphQL presents a learning curve for developers familiar with REST APIs.
• GraphQL shifts much of the work of a data query to the server side, which adds complexity for server developers.
• Depending on how it is implemented, GraphQL might require different API management strategies than REST APIs, particularly when considering rate limits and pricing.
• Caching is more complex than with REST.
• API maintainers have the additional task of writing maintainable GraphQL schema.

Next Steps

To learn more about GraphQL, see the official documentation here

To use our official playground, check out the GraphiQL Playground section here and see which commands you can use by reading our documentation [here] (https://api-docs.pipefy.com/reference/queries/)