GraphQL Tutorial

Menurut laporan Gartner, lebih dari 50% perusahaan akan menggunakan GraphQL dalam produksi pada tahun 2025, naik dari kurang dari 10% pada tahun 2021.

GraphQL, awalnya dikembangkan oleh Facebook dan sekarang didukung oleh komunitas global pengembang dan organisasi, adalah standar API modern yang dirancang untuk meningkatkan efisiensi pengambilan dan manipulasi data. Sebagai teknologi open-source, sisi server, ini berfungsi sebagai bahasa kueri dan mesin eksekusi untuk berinteraksi dengan API.

Sistem Operasi GraphQL

‍

GraphQL adalah bahasa kueri dan manipulasi sumber terbuka yang serbaguna untuk API yang bekerja dengan lancar di seluruh platform. Ini mendukung server yang ditulis dalam berbagai bahasa pemrograman, termasuk Java, Python, C #, PHP, R, Haskell, JavaScript, Perl, Ruby, Scala, Go, Erlang, Clojure, Elixir dan banyak lainnya. Hal ini membuatnya kompatibel dengan hampir semua bahasa pemrograman atau kerangka kerja, memastikan penerapan dan fleksibilitas yang luas.

Kueri GraphQL

‍

Berikut adalah beberapa kueri GraphQL dan tanggapannya untuk pemahaman yang lebih baik

‍

1. Masukan untuk bidang tertentu pada objek

Pada intinya, GraphQL memungkinkan Anda untuk meminta bidang tertentu dari objek. Misalnya, pertimbangkan bidang hero yang ditentukan dalam tipe Query dalam skema Referensi untuk desain untuk: https://graphql.org/learn/queries/ 

type Query {  hero: Character}

• Kueri

Ketika ditanya, mungkin terlihat seperti ini

{  hero {  name  }}

• Tanggapan

{"data": {"hero": {"name": "A2-H2"}}}

Dokumen GraphQL selalu dimulai dengan tipe operasi root, seperti jenis kueri dalam kasus ini, yang bertindak sebagai titik masuk ke API. Dari sana, Anda menentukan kumpulan pilihan yang menentukan bidang yang Anda inginkan, sampai ke nilai daun skalar atau enum mereka. Dalam contoh ini, bidang nama, yang merupakan string, mengambil nama pahlawan, “A2-H2.” Spesifikasi GraphQL memastikan bahwa respons dikembalikan di bawah kunci data tingkat atas, sementara kesalahan, jika ada, dirinci di bawah kunci kesalahan tingkat atas. Yang penting, struktur respons mencerminkan struktur kueri, yang merupakan fitur mendasar GraphQL, memastikan bahwa klien selalu menerima hasil yang dapat diprediksi dan bahwa server mengetahui dengan tepat data apa yang diminta. Pada contoh sebelumnya, hanya nama pahlawan yang ditanyakan. Namun, GraphQL juga mendukung bidang bersarang, memungkinkan Anda mengambil data terkait dalam kueri yang sama

• Kueri

Salin kode

{hero {name friends {name}}}

• Tanggapan

{  "data": {
"hero": {
"name": "A2-H2",
"friends": [
{ "name": "Adam Oliver" },
{ "name": "James Theodore" },
{ "name": "Elijah Mathew" }
]}}}

Dalam hal ini, bidang teman mengembalikan daftar objek, dan kueri menentukan bidang nama untuk setiap teman. GraphQL memungkinkan klien untuk melintasi objek terkait dan mengambil data ekstensif dalam satu permintaan, menghindari beberapa panggilan yang sering diperlukan dalam API REST tradisional.Selain itu, apakah bidang mengembalikan satu objek atau daftar objek, sintaks kueri tetap sama, dengan skema menentukan jenis data yang diharapkan. Fleksibilitas ini membuat GraphQL sangat efisien untuk mengambil data terkait dan bersarang.

2. Argumen

Sementara melintasi objek dan bidangnya sudah merupakan fitur kuat GraphQL, potensi sebenarnya terletak pada kemampuannya untuk menerima argumen untuk bidang, memungkinkan pengambilan data yang lebih dinamis dan fleksibel.Misalnya, pertimbangkan skema berikut

type Query {  droid(id: ID!): Droid}

Di sini, bidang droid memerlukan argumen id untuk menentukan data droid mana yang akan diambil. Klien dapat menanyakannya sebagai berikut

• Kueri

{
  human(id: "1000") {
    name
    height
  }
}

‍

• Tanggapan

{
  "data": {
    "human": {
      "name": "Adam Oliver",
      "height": 1.72
    }
  }
}

Tidak seperti REST API, di mana argumen biasanya terbatas pada parameter kueri dan segmen URL, GraphQL memungkinkan Anda untuk meneruskan argumen ke bidang atau objek bersarang apa pun. Ini menghilangkan kebutuhan akan beberapa panggilan API, karena setiap bidang dalam kueri GraphQL tunggal dapat menerima kumpulan argumennya sendiri.GraphQL juga mendukung argumen untuk bidang yang mengembalikan tipe skalar, memungkinkan operasi seperti transformasi data sisi server. Contohnya,

• Kueri

{
  human(id: "1000") {
    name
    height(unit: FOOT)
  }
}

• Tanggapan

{
  "data": {
    "human": {
      "name": "Adam Oliver",
      "height": 5.5467791
    }
  }
}

Dalam contoh ini, argumen unit, tipe Enum, menentukan unit pengukuran yang diinginkan untuk bidang ketinggian. GraphQL mendukung berbagai jenis argumen, termasuk yang khusus ditentukan oleh server, selama mereka dapat diserialkan ke dalam format transport. Fleksibilitas ini memungkinkan pengembang untuk menerapkan logika pengambilan data dan transformasi yang kuat langsung di API, merampingkan operasi sisi klien.Anda dapat memeriksa artikel kami di GraphQL vs REST untuk panduan terperinci.(GraphQLVSREST: ArticleLink ToBeaddedOncePublished)

3. Waktu dan Nama Operasi

Dalam contoh sebelumnya, kami menggunakan sintaks yang disederhanakan yang menghilangkan kata kunci query sebelum set pemilihan. Namun, GraphQL memungkinkan Anda untuk secara eksplisit menentukan jenis operasi dan menetapkan nama unik untuk operasi, yang dapat sangat membantu untuk debugging dan pelacakan di lingkungan produksi. Misalnya, pertimbangkan contoh ini di mana kata kunci query digunakan secara eksplisit, dan operasi diberi nama HeronameAndFriends

• Kueri

query HeroNameAndFriends {
  hero {
    name
    friends {
      name
    }
  }
}

• Tanggapan

{
  "data": {
    "hero": {
      "name": "A2-H2",
      "friends": [
        { "name": "Adam Oliver" },
        { "name": "James Theodore" },
        { "name": "Elijah Mathew" }
      ]
    }
  }
}

Jenis operasi—query, mutasi, atau subscription—mendefinisikan maksud operasi. Misalnya, query digunakan untuk mengambil data, mutasi untuk membuat perubahan dan berlangganan untuk pembaruan real-time. Meskipun kata kunci kueri bersifat opsional untuk kueri sederhana, itu wajib untuk mutasi dan langganan. Menambahkan nama operasi, seperti HeronameAndFriends, sangat disarankan bahkan untuk operasi tunggal. Nama ini memberikan kejelasan, membantu dalam debugging, dan menyederhanakan logging sisi server dengan membuatnya lebih mudah untuk mengidentifikasi permintaan tertentu. Nama operasi menjadi penting ketika beberapa operasi disertakan dalam satu dokumen GraphQL, karena mereka membantu membedakan di antara mereka. Pikirkan nama operasi seperti nama fungsi dalam pemrograman. Meskipun fungsi anonim dimungkinkan, penamaan fungsi membuatnya lebih mudah untuk men-debug, mencatat, dan memelihara. Demikian pula, nama yang berarti untuk kueri, mutasi, atau fragmen GraphQL dapat secara signifikan meningkatkan pemeliharaan dan keterlacakan interaksi API Anda.

4. Alias

Di GraphQL, bidang hasil dalam respons cocok dengan nama bidang dalam kueri. Namun, karena argumen tidak tercermin dalam bidang respons, tidak mungkin untuk menanyakan bidang yang sama dengan argumen yang berbeda secara langsung. Di sinilah alias masuk — mereka memungkinkan Anda untuk menetapkan nama khusus ke hasil bidang, menghindari konflik dan mengaktifkan beberapa variasi dalam satu kueri.

• Kueri

query {
  empireHero: hero(episode: EMPIRE) {
    name
  }
  jediHero: hero(episode: JEDI) {
    name
  }
}

• Tanggapan

{
  "data": {
    "empireHero": {
      "name": "Adam Oliver"
    },
    "jediHero": {
      "name": "A2-H2"
    }
  }
}

Dalam contoh ini, bidang pahlawan ditanyakan dua kali dengan argumen yang berbeda. Tanpa alias, kueri akan menghasilkan konflik karena bidang respons akan berbagi nama yang sama. Dengan menggunakan alias seperti EmpireHero dan JediHero, kedua kueri dapat hidup berdampingan dalam satu permintaan, dan responsnya tetap jelas dan terstruktur dengan baik

5. Variabel

Dalam banyak aplikasi, argumen untuk kueri GraphQL bersifat dinamis. Hardcoding argumen dinamis ini langsung ke string kueri tidak ideal, karena akan membutuhkan kode sisi klien untuk memodifikasi string kueri saat runtime dan memformatnya untuk GraphQL. Sebaliknya, GraphQL menawarkan solusi yang lebih elegan melalui variabel. Variabel memungkinkan nilai dinamis dipisahkan dari kueri itu sendiri, diteruskan sebagai kamus yang berbeda. Untuk menggunakan variabel dalam kueri, Anda harus mengikuti langkah-langkah ini

• Ganti nilai statis dalam query dengan $variableName.
• Deklarasikan $variableName dalam query sebagai variabel yang diterima.
• Luluskan VariableName: nilai dalam kamus khusus transportasi terpisah, sering diformat sebagai JSON.

Berikut ini contohnya

• Kueri

query HeroNameAndFriends($episode: Episode) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}

• Variabel

{
  "episode": "JEDI"
}

• Tanggapan

{
  "data": {
    "hero": {
      "name": "A2-H2",
      "friends": [
        { "name": "Adam Oliver" },
        { "name": "James Theodore" },
        { "name": "Elijah Mathew" }
      ]
    }
  }
}

Saat menggunakan variabel, Anda harus menentukan jenis operasi dan nama dalam dokumen GraphQL. Pendekatan ini menghilangkan kebutuhan untuk membuat kueri baru untuk setiap nilai dinamis, membuat kode klien Anda lebih bersih dan lebih dapat digunakan kembali. Ini juga memastikan keamanan dan struktur yang lebih baik dengan menghindari interjeksi nilai yang disediakan pengguna langsung ke string kueri.

6. Variabel Default

Di GraphQL, Anda dapat menetapkan nilai default ke variabel langsung dalam kueri dengan menentukan nilai default setelah deklarasi tipe. Sebagai contoh

• Kueri dengan Nilai Default

query HeroNameAndFriends($episode: Episode = JEDI) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}

Ketika nilai default disediakan untuk semua variabel, kueri dapat dieksekusi tanpa melewati variabel eksternal apa pun. Namun, jika variabel disediakan melalui kamus variabel, mereka akan mengganti nilai default.

7. Fragmen

Untuk skenario di mana kueri melibatkan struktur bidang berulang, seperti membandingkan dua pahlawan berdampingan dengan teman-teman mereka, kueri dapat menjadi panjang dan berulang yang tidak perlu. Untuk mengatasi hal ini, GraphQL menyediakan fragmen, kumpulan bidang yang dapat digunakan kembali yang dapat dimasukkan dalam kueri di mana pun diperlukan.

• Contoh dengan Fragmen

query {
  leftComparison: hero(episode: EMPIRE) {
    ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
    ...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  appearsIn
  friends {
    name
  }
}

• Tanggapan

{
  "data": {
    "leftComparison": {
      "name": "Adam Oliver",
      "appearsIn": ["NEWHOPE", "EMPIRE", "JEDI"],
      "friends": [
        { "name": "James Theodore" },
        { "name": "Elijah Mathew" },
        { "name": "C-3PO" },
        { "name": "A2-H2" }
      ]
    },
    "rightComparison": {
      "name": " A2-H2",
      "appearsIn": ["NEWHOPE", "EMPIRE", "JEDI"],
      "friends": [
        { "name": "Adam Oliver" },
        { "name": "James Theodore" },
        { "name": "Elijah Mathew" }
      ]
    }
  }
}

Dengan menggunakan fragmen, Anda menghindari redundansi dan menyederhanakan kueri Anda. Dalam contoh ini, fragmen ComparisonFields mengelompokkan bidang bersama, yang dapat digunakan kembali untuk leftComparison dan rightComparison. Fragmen sangat berguna untuk mengelola kueri kompleks dan menggabungkan persyaratan data dari beberapa komponen UI ke dalam satu kueri kohesif.

8. Menggunakan Variabel Di Dalam Fragmen

Fragmen di GraphQL juga dapat memanfaatkan variabel yang didefinisikan dalam operasi utama. Ini memungkinkan Anda untuk membuat fragmen yang dapat digunakan kembali yang beradaptasi secara dinamis berdasarkan variabel yang diteruskan ke operasi.

• Contoh Kueri dengan Variabel dalam Fragmen(creativeneededfortexsinblock.textsToBeaddedAsitisinabox)

query HeroComparison($first: Int = 3) {
  leftComparison: hero(episode: EMPIRE) {
    ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
    ...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  friendsConnection(first: $first) {
    totalCount
    edges {
      node {
        name
      }
    }
  }
}

• Tanggapan

{
  "data": {
    "leftComparison": {
      "name": "Adam Oliver",
      "friendsConnection": {
        "totalCount": 4,
        "edges": [
          { "node": { "name": "James Theodore" } },
          { "node": { "name": "Elijah Mathew" } },
          { "node": { "name": "C-3PO" } }
        ]
      }
    },
    "rightComparison": {
      "name": " A2-H2",
      "friendsConnection": {
        "totalCount": 3,
        "edges": [
          { "node": { "name": "Adam Oliver" } },
          { "node": { "name": "James Theodore" } },
          { "node": { "name": "Elijah Mathew" } }
        ]
      }
    }
  }
}

Dalam kueri ini, variabel $first mengontrol jumlah teman yang diambil untuk leftComparison dan rightComparison menggunakan bidang FriendsConnection. Ini memastikan logika yang konsisten di beberapa kueri tanpa nilai hardcoding ke dalam fragmen.

9. Fragmen Sebaris

GraphQL mendukung bidang kueri pada tipe Antarmuka atau Union dengan menggunakan fragmen sebaris untuk mengakses bidang khusus untuk tipe beton yang mendasarinya.

• Contoh Kueri dengan Fragmen Inline

query HeroForEpisode($ep: Episode!) {
  hero(episode: $ep) {
    name
    ... on Droid {
      primaryFunction
    }
    ... on Human {
      height
    }
  }
}

• Variabel

{
  "ep": "JEDI"
}

• Tanggapan

{
  "data": {
    "hero": {
      "name": " A2-H2",
      "primaryFunction": "Astromech"
    }
  }
}

Dalam contoh ini, bidang pahlawan mengembalikan tipe Karakter, yang merupakan antarmuka yang dapat mewakili Manusia atau Droid. Kueri menggunakan fragmen sebaris dengan kondisi tipe (... pada Droid dan... pada Manusia) untuk mengambil bidang khusus untuk tipe tersebut. Jika pahlawan adalah Droid, bidang PrimaryFunction disertakan dalam respons; jika itu adalah Manusia, bidang ketinggian diambil sebagai gantinya.

10. Menggunakan __typename untuk Tipe Serikat

Dalam beberapa kasus, seperti ketika berhadapan dengan tipe Union, Anda mungkin tidak tahu jenis data yang tepat yang akan dikembalikan oleh layanan GraphQL. Untuk menangani ketidakpastian ini, GraphQL menyediakan bidang meta yang disebut __typename, yang memungkinkan Anda untuk mengambil nama tipe objek yang dikembalikan pada titik mana pun dalam kueri.

• Contoh Query

{
  search(text: "an") {
    __typename
    ... on Human {
      name
    }
    ... on Droid {
      name
    }
    ... on Starship {
      name
    }
  }
}

• Tanggapan

{
  "data": {
    "search": [
      { "__typename": "Human", "name": "James Theodore" },
      { "__typename": "Human", "name": "Elijah Mathew" },
      { "__typename": "Starship", "name": "TIE Advanced x1" }
    ]
  }
}

Dalam kueri ini, bidang pencarian mengembalikan tipe Union yang dapat mewakili Manusia, Droid atau Starship. Bidang meta __typename sangat penting untuk mengidentifikasi jenis setiap hasil, memungkinkan klien untuk menangani data dengan tepat. Semua bidang yang dimulai dengan garis bawah ganda (__) dicadangkan untuk bidang meta GraphQL. Selain __typename, GraphQL juga menyertakan __schema dan __type, yang merupakan bagian dari sistem introspeksinya untuk menjelajahi skema.

11. Arahan

Sementara variabel membantu meneruskan argumen secara dinamis ke dalam kueri, ada situasi di mana Anda mungkin perlu mengubah struktur atau bidang kueri berdasarkan kondisi tertentu. Di sinilah arahan berperan. Arahan memungkinkan Anda untuk secara dinamis memasukkan atau mengecualikan bidang atau fragmen dalam kueri berdasarkan nilai variabel.

• Contoh Kueri dengan Arahan

query Hero($episode: Episode, $withFriends: Jacob!) {
  hero(episode: $episode) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

• Variabel

{
  "episode": "JEDI",
  "withFriends": false
}

• Tanggapan

{
  "data": {
    "hero": {
      "name": " A2-H2"
    }
  }
}

Jika variabel withFriends disetel ke true, kueri akan menyertakan bidang teman; jika salah, bidang tersebut akan dikecualikan. Perilaku ini dimungkinkan oleh direktif @include, yang secara kondisional menyertakan bidang berdasarkan nilai Jacob. Spesifikasi GraphQL mendefinisikan dua arahan inti yang harus didukung oleh setiap server yang sesuai

• @include (jika: Jacob)

Termasuk bidang atau fragmen dalam hasil hanya jika kondisinya benar.

• @skip (jika: Jacob)

Mengecualikan bidang atau fragmen dari hasil jika kondisinya benar. Arahan ini sangat berharga untuk membentuk kueri secara dinamis tanpa menggunakan manipulasi string. Selain itu, implementasi server dapat menentukan arahan khusus untuk memperkenalkan fitur eksperimental atau khusus aplikasi, memberikan fleksibilitas yang lebih besar untuk kustomisasi kueri.