16 Mengenal Query GraphQL dan Format Standarnya

title: “16 Mengenal Query GraphQL dan Format Standarnya” date: 2024-06-18 author: “Engineer Dev” tags: [GraphQL, Backend, API, Query Language]

Pendahuluan

Sebagai seorang engineer backend, cukup sering saya menemukan pertanyaan soal GraphQL. Tapi, meski sudah ramai digunakan, pemahaman soal query dan format standarnya kadang masih minim. Artikel ini akan membedah 16 aspek penting dalam mengenal Query GraphQL dan format bakunya, lengkap dengan contoh praktik, simulasi, dan sedikit diagram flow supaya lebih mudah dicerna.

1. Apa Itu GraphQL?

GraphQL adalah query language untuk API yang dibuat oleh Facebook di 2012 dan dirilis secara open-source di 2015. Berbeda dengan REST, GraphQL memungkinkan klien menentukan data apa saja yang mereka butuhkan.

2. Dasar Sintaks Query

Query di GraphQL menggunakan bentuk deklaratif, bukan imperative. Misalnya, untuk mengambil user:

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

3. Tipe Query Standar

GraphQL pada dasarnya mengenal tiga tipe request utama:

Biasanya, query digunakan untuk read-only requests.

4. Struktur Dasar Query

Struktur format query standar:

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

Misal:

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

5. Query dengan Argument

Arguments diterapkan setelah entitas. Contoh dengan filtering dan pagination:

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

6. Alias pada Query

Alias dipakai bila perlu dua data berbeda dari satu field:

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

7. Variables pada Query

Agar query lebih dynamic dan secure dari injection, pakai 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 Query

GraphQL mendukung nested request, misal user dengan posts mereka:

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

9. Fragments

Agar reusable, gunakan fragment. Contoh:

 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

Untuk skema dengan 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

Directive menambah logika pada query, misal @skip dan @include:

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

12. Handling Error dan Response

Response GraphQL standarnya:

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

13. Mutasi: Update dan Tambah Data

Mutation untuk update/tambah data:

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

14. Subscription

Untuk real-time update:

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

15. Standar Format Response

Response GraphQL selalu dalam format berikut:

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

Perbedaan dengan REST: GraphQL hanya mempunyai satu endpoint (misal /graphql). Semua query masuk ke sana.

16. Flow Query Execution

Mari lihat bagaimana flow query GraphQL dijalankan pada server. Berikut diagramnya dengan 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]

Simulasi: Lengkap dalam Satu Query

Misal Anda ingin mengambil 2 user berbeda, berikut post mereka dan total comment pada tiap post. Dengan GraphQL, semua bisa sekaligus:

 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}

Response-nya:

 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}

Tabel: REST vs GraphQL Query

Penutup

Mengenali query dan format standar GraphQL adalah pondasi untuk membangun API modern yang fleksibel dan efisien. Dengan arsitektur GraphQL, klien bebas mengambil data sesuai kebutuhan tanpa overfetching, less endpoint, dan strong typing.

Mulai dari struktur dasar, fragment, variables, mutation, hingga subscription—semuanya diatur dalam satu format standar yang mudah dipelajari namun powerful dalam praktiknya. Untuk engineer backend, memahami format query dan standar response GraphQL adalah investasi penting demi pengalaman API yang lebih solid ke depan.

Happy querying! 🚀

Referensi:

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

Ingin eksplor lebih dalam?

Komen di bawah untuk tanya tentang implementasi, best practice, dan use-case nyata GraphQL di production!