16 Getting to Know GraphQL Queries and Their Standard Format

title: “16 Getting to Know GraphQL Queries and Their Standard Format” date: 2024-06-18 author: “Engineer Dev” tags: [GraphQL, Backend, API, Query Language]

Introduction

As a backend engineer, I run into questions about GraphQL fairly often. But even though it is widely used these days, understanding of queries and their standard format is sometimes still lacking. This article breaks down 16 important aspects of getting to know GraphQL Queries and their canonical format, complete with practical examples, simulations, and a bit of a flow diagram to make it easier to digest.

1. What Is GraphQL?

GraphQL is a query language for APIs created by Facebook in 2012 and released as open source in 2015. Unlike REST, GraphQL lets clients specify exactly what data they need.

2. Query Syntax Basics

Queries in GraphQL use a declarative form rather than an imperative one. For example, to fetch a user:

1{
2  user(id: "42") {
3    id
4    name
5    email
6  }
7}

3. Standard Query Types

At its core, GraphQL recognizes three main request types:

Typically, query is used for read-only requests.

4. Basic Query Structure

The standard query format structure:

1{
2  <entity>(<arguments>) {
3    <fields>
4    <sub-entity> {
5      <fields>
6    }
7  }
8}

For example:

1{
2  posts(limit: 2) {
3    id
4    title
5    author {
6      name
7    }
8  }
9}

5. Queries with Arguments

Arguments are applied after the entity. Here is an example with filtering and pagination:

1{
2  posts(title: "GraphQL", limit: 2, offset: 0) {
3    id
4    title
5  }
6}

6. Aliases in Queries

Aliases are used when you need two different sets of data from the same field:

1{
2  firstUser: user(id: "1") {
3    name
4  }
5  secondUser: user(id: "2") {
6    name
7  }
8}

7. Variables in Queries

To make queries more dynamic and secure against injection, use variables:

Query:

1query getUser($userId: ID!) {
2  user(id: $userId) {
3    id
4    name
5  }
6}

Variables (JSON):

1{
2  "userId": "5"
3}

8. Nested Queries

GraphQL supports nested requests, for example a user along with their posts:

 1{
 2  user(id: "5") {
 3    id
 4    name
 5    posts {
 6      title
 7      content
 8    }
 9  }
10}

9. Fragments

To make things reusable, use fragments. For example:

 1fragment userFragment on User {
 2  id
 3  name
 4  email
 5}
 6
 7{
 8  user(id: "10") {
 9    ...userFragment
10    posts {
11      title
12    }
13  }
14}

10. Inline Fragments

For schemas with union types:

 1{
 2  search(text: "foo") {
 3    ... on User {
 4      name
 5      email
 6    }
 7    ... on Post {
 8      title
 9      content
10    }
11  }
12}

11. Directives

Directives add logic to a query, such as @skip and @include:

1query getUser($includeEmail: Boolean!) {
2  user(id: "7") {
3    name
4    email @include(if: $includeEmail)
5  }
6}

12. Handling Errors and Responses

A standard GraphQL response:

 1{
 2  "data": {/* ... */},
 3  "errors": [
 4    {
 5      "message": "User not found",
 6      "locations": [{"line":3, "column":5}],
 7      "path": ["user"]
 8    }
 9  ]
10}

13. Mutations: Updating and Adding Data

Mutations to update/add data:

1mutation {
2  addPost(title: "Format GraphQL", content: "Penjelasan.") {
3    id
4    title
5  }
6}

14. Subscriptions

For real-time updates:

1subscription {
2  postAdded {
3    id
4    title
5    author {
6      name
7    }
8  }
9}

15. Standard Response Format

A GraphQL response is always in the following format:

1{
2  "data": {
3    "user": {
4      "id": "5",
5      "name": "Andi"
6    }
7  },
8  "errors": []
9}

Difference from REST: GraphQL has only a single endpoint (for example /graphql). All queries go through it.

16. Query Execution Flow

Let’s look at how a GraphQL query flow is executed on the server. Here is the diagram using Mermaid:

flowchart TD
    A[Client mengirim Query] --> B[GraphQL Server menerima request]
    B --> C[Parsing Query & Validasi]
    C --> D[Ambil Resolver masing-masing Field]
    D --> E[Eksekusi Resolver (ambil dari DB/Service/Cache)]
    E --> F[Build Response Object]
    F --> G[Kirim Response ke Client]

flowchart TD
    A[Client mengirim Query] --> B[GraphQL Server menerima request]
    B --> C[Parsing Query & Validasi]
    C --> D[Ambil Resolver masing-masing Field]
    D --> E[Eksekusi Resolver (ambil dari DB/Service/Cache)]
    E --> F[Build Response Object]
    F --> G[Kirim Response ke Client]

Simulation: Everything in a Single Query

Suppose you want to fetch two different users, along with their posts and the total number of comments on each post. With GraphQL, you can get it all at once:

 1query GetUsersPosts {
 2  user1: user(id: "1") {
 3    name
 4    posts {
 5      title
 6      commentsCount
 7    }
 8  }
 9  user2: user(id: "2") {
10    name
11    posts {
12      title
13      commentsCount
14    }
15  }
16}

The response:

 1{
 2  "data": {
 3    "user1": {
 4      "name": "Andi",
 5      "posts": [
 6        {"title": "Intro GraphQL", "commentsCount": 4}
 7      ]
 8    },
 9    "user2": {
10      "name": "Budi",
11      "posts": [
12        {"title": "Belajar REST", "commentsCount": 1}
13      ]
14    }
15  }
16}

Table: REST vs GraphQL Query

Conclusion

Getting to know GraphQL queries and their standard format is the foundation for building modern APIs that are flexible and efficient. With a GraphQL architecture, clients are free to fetch exactly the data they need without overfetching, with fewer endpoints, and strong typing.

From basic structure, fragments, variables, and mutations all the way to subscriptions—everything is governed by a single standard format that is easy to learn yet powerful in practice. For backend engineers, understanding GraphQL’s query format and standard response is an important investment toward a more solid API experience going forward.

Happy querying! 🚀

References:

• https://graphql.org/learn/queries/
• https://spec.graphql.org/June2018/
• https://www.apollographql.com/docs/

Want to explore further?

Drop a comment below to ask about implementation, best practices, and real-world use cases of GraphQL in production!