Kasus penggunaan untuk versioning field dan directive

Harap baca terlebih dahulu panduan Mengembangkan skema melalui versioning field, yang menjelaskan fitur "field versioning" di Gato GraphQL.

Gato GraphQL memungkinkan field dan directive menerima argumen versionConstraint, untuk memilih versi spesifik (yaitu implementasi) dari field/directive yang akan digunakan:

query GetPosts {
  posts(versionConstraint: "^1.0") {
    id
    title(versionConstraint: ">=2.1")
    excerpt @strUpperCase(versionConstraint: "~1.5.3")
  }
}Copy

Sebuah field (atau directive) juga dapat memiliki implementasi default, yaitu implementasi yang tidak memiliki versi (dan merupakan implementasi yang digunakan ketika versionConstraint tidak disertakan dalam query).

Saat melakukan introspeksi, hanya data untuk field dan directive default yang diambil. Sebagai konsekuensinya, argumen versionConstraint tidak akan pernah muncul saat melakukan introspeksi, karena field atau directive default tidak mendukungnya.

Karena hal ini, kita selalu harus mengetahui terlebih dahulu bahwa sebuah field atau directive memiliki dua versi atau lebih untuk dipilih, dan kita harus mengetahui nomor versi tersebut. Informasi ini, secara default, tidak bersifat publik.

Lalu, apa manfaat versioning? Berikut beberapa kasus penggunaannya.

​

Menyediakan perbaikan bug cepat untuk pengguna tertentu

Katakanlah Anda memiliki GraphQL API yang di-deploy di situs web Anda, dan seorang pengguna tertentu mengeluhkan bahwa field tidak berfungsi sebagaimana mestinya. Namun hal ini hanya terjadi untuk pengguna tersebut; tidak ada orang lain yang tampaknya mengalami masalah.

Anda mengidentifikasi dan memperbaiki masalah tersebut, tetapi ingin memastikan perbaikan itu berfungsi sebelum men-deploy perubahan ke semua orang. Anda dapat men-deploy perubahan tersebut di bawah field resolver baru dengan versi "1.0.1", dan meminta pengguna yang bermasalah untuk mengubah GraphQL query agar mengarah ke versi field ini:

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

Jika bug memang telah diperbaiki, baru kemudian salin kode ke field resolver default.

​

Meminta pengguna terpilih untuk menguji rilis mendatang

Jika sebuah field atau directive diberi versi, dan tidak memiliki implementasi default (yaitu tidak diberi versi), maka field atau directive tersebut tidak akan muncul sama sekali saat introspeksi.

{
  someField
    # Directive ini tidak memiliki implementasi default,
    # sehingga tidak akan muncul saat introspeksi,
    # tetapi masih dapat ditambahkan dalam GraphQL query
    # ketika memberikan constraint yang memenuhinya
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

Anda kemudian dapat men-deploy field atau directive tersebut dan tidak akan terlihat di GraphQL API, lalu meminta pengguna terpilih untuk mengujinya, di mana mereka harus memasukkan argumen versionConstraint yang sesuai dalam query mereka untuk menggunakannya.

Setelah diterima, versioning dihapus, dan field atau directive menjadi terlihat melalui introspeksi, sehingga tersedia untuk semua orang.