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:

{
  user(id: "42") {
    id
    name
    email
  }
}

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:

{
  <entity>(<arguments>) {
    <fields>
    <sub-entity> {
      <fields>
    }
  }
}

Misal:

{
  posts(limit: 2) {
    id
    title
    author {
      name
    }
  }
}

5. Query dengan Argument

Arguments diterapkan setelah entitas. Contoh dengan filtering dan pagination:

{
  posts(title: "GraphQL", limit: 2, offset: 0) {
    id
    title
  }
}

6. Alias pada Query

Alias dipakai bila perlu dua data berbeda dari satu field:

{
  firstUser: user(id: "1") {
    name
  }
  secondUser: user(id: "2") {
    name
  }
}

7. Variables pada Query

Agar query lebih dynamic dan secure dari injection, pakai variables:

Query:

query getUser($userId: ID!) {
  user(id: $userId) {
    id
    name
  }
}

Variables (JSON):

{
  "userId": "5"
}

8. Nested Query

GraphQL mendukung nested request, misal user dengan posts mereka:

{
  user(id: "5") {
    id
    name
    posts {
      title
      content
    }
  }
}

9. Fragments

Agar reusable, gunakan fragment. Contoh:

fragment userFragment on User {
  id
  name
  email
}

{
  user(id: "10") {
    ...userFragment
    posts {
      title
    }
  }
}

10. Inline Fragments

Untuk skema dengan union types:

{
  search(text: "foo") {
    ... on User {
      name
      email
    }
    ... on Post {
      title
      content
    }
  }
}

11. Directives

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

query getUser($includeEmail: Boolean!) {
  user(id: "7") {
    name
    email @include(if: $includeEmail)
  }
}

12. Handling Error dan Response

Response GraphQL standarnya:

{
  "data": {/* ... */},
  "errors": [
    {
      "message": "User not found",
      "locations": [{"line":3, "column":5}],
      "path": ["user"]
    }
  ]
}

13. Mutasi: Update dan Tambah Data

Mutation untuk update/tambah data:

mutation {
  addPost(title: "Format GraphQL", content: "Penjelasan.") {
    id
    title
  }
}

14. Subscription

Untuk real-time update:

subscription {
  postAdded {
    id
    title
    author {
      name
    }
  }
}

15. Standar Format Response

Response GraphQL selalu dalam format berikut:

{
  "data": {
    "user": {
      "id": "5",
      "name": "Andi"
    }
  },
  "errors": []
}

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]

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:

query GetUsersPosts {
  user1: user(id: "1") {
    name
    posts {
      title
      commentsCount
    }
  }
  user2: user(id: "2") {
    name
    posts {
      title
      commentsCount
    }
  }
}

Response-nya:

{
  "data": {
    "user1": {
      "name": "Andi",
      "posts": [
        {"title": "Intro GraphQL", "commentsCount": 4}
      ]
    },
    "user2": {
      "name": "Budi",
      "posts": [
        {"title": "Belajar REST", "commentsCount": 1}
      ]
    }
  }
}

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!