Pengantar GraphQL.

GraphQL adalah bahasa query untuk API yang memungkinkan klien meminta persis data yang dibutuhkan, tidak lebih dan tidak kurang — berbeda dari REST API yang biasanya mengembalikan struktur data tetap dari setiap endpoint.

Masalah yang Dijawab GraphQL

Pada REST API, endpoint seperti /pengguna/1 bisa saja mengembalikan puluhan field padahal klien hanya butuh nama dan emailnya saja (over-fetching), atau sebaliknya perlu memanggil beberapa endpoint sekaligus untuk mengumpulkan data yang saling berkaitan (under-fetching). GraphQL mengatasi keduanya lewat satu endpoint fleksibel yang bentuknya ditentukan oleh permintaan klien.

Query: Mengambil Data

query {
  pengguna(id: 1) {
    nama
    email
    postingan {
      judul
    }
  }
}

Hasilnya persis mengikuti struktur yang diminta:

{
  "data": {
    "pengguna": {
      "nama": "Rangga",
      "email": "[email protected]",
      "postingan": [
        { "judul": "Belajar GraphQL" }
      ]
    }
  }
}

Mutation: Mengubah Data

Jika query dipakai untuk membaca data, mutation dipakai untuk membuat, mengubah, atau menghapus data.

mutation {
  buatPostingan(judul: "Judul Baru", isi: "Isi artikel...") {
    id
    judul
  }
}

Schema dan Type

Setiap API GraphQL memiliki schema yang mendefinisikan tipe data dan operasi apa saja yang tersedia, berfungsi sebagai kontrak antara server dan klien.

type Pengguna {
  id: ID!
  nama: String!
  email: String!
  postingan: [Postingan!]!
}

type Postingan {
  id: ID!
  judul: String!
}

Tanda ! menandakan field tersebut wajib ada (non-null).

Memanggil GraphQL dari JavaScript

async function ambilPengguna(id) {
  const respons = await fetch("https://api.contoh.com/graphql", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: `
        query {
          pengguna(id: ${id}) {
            nama
            email
          }
        }
      `,
    }),
  });

  const { data } = await respons.json();
  return data.pengguna;
}

Berbeda dari REST yang biasanya memakai banyak endpoint dengan method HTTP berbeda (GET, POST, dst), GraphQL pada umumnya hanya memakai satu endpoint dan selalu memakai method POST.

Kesimpulan

GraphQL memberi klien kendali penuh atas bentuk data yang diminta lewat query yang fleksibel, mengurangi masalah over-fetching dan under-fetching yang umum terjadi di REST API. Sebagai gantinya, tim yang membangun API perlu merancang schema dengan cermat sejak awal, karena schema tersebut menjadi kontrak utama antara server dan seluruh klien yang menggunakannya.