Persisted Queries
REST'teki gibi önceden tanımlanmış endpoint'ler oluşturmak için GraphQL queries kullanın ve her iki API'nin avantajlarından yararlanın.
Açıklama
REST ile birden fazla endpoint oluşturursunuz; her biri önceden tanımlanmış bir veri kümesi döndürür.
| Avantajlar | Dezavantajlar |
|---|---|
| ✅ Basittir | ❌ Tüm endpoint'leri oluşturmak zahmetlidir |
✅ GET veya POST ile erişilebilir | ❌ Bir proje, endpoint'lerin hazır olmasını beklerken darboğazlarla karşılaşabilir |
| ✅ Sunucuda veya CDN'de önbelleğe alınabilir | ❌ Belge üretmek zorunludur |
| ✅ Güvenlidir: yalnızca amaçlanan veriler açığa çıkar | ❌ Yavaş olabilir (özellikle mobil uygulamalar için), çünkü uygulama tüm verileri almak için birden fazla istek göndermek zorunda kalabilir |
GraphQL ile tek bir endpoint'e herhangi bir query gönderirsiniz ve bu endpoint tam olarak istenen verileri döndürür.
| Avantajlar | Dezavantajlar |
|---|---|
| ✅ Veri eksik/fazla çekme sorunu yoktur | ❌ Yalnızca POST ile erişilebilir |
| ✅ Tüm veriler tek bir istekte alındığından hızlı olabilir | ❌ Sunucuda veya CDN'de önbelleğe alınamaz; bu da olduğundan daha yavaş ve pahalı olmasına yol açar |
| ✅ Projenin hızlı iterasyonunu sağlar | ❌ Dosya yükleme veya önbelleğe alma gibi konularda tekerleği yeniden icat etmeyi gerektirebilir |
| ✅ Kendi kendini belgeleyebilir | ❌ N+1 problemi gibi ek karmaşıklıklarla başa çıkmak gerekir |
| ✅ Query için bir editör (GraphiQL) sağlar ve bu işi kolaylaştırır |
Persisted queries bu 2 yaklaşımı bir araya getirir:
- Queries oluşturmak ve çözmek için GraphQL kullanır
- Ancak tek bir endpoint açmak yerine, önceden tanımlanmış her query'yi kendi endpoint'i altında sunar
Bu sayede REST'teki gibi önceden tanımlanmış verilerle birden fazla endpoint elde ederiz; ancak bunlar GraphQL kullanılarak oluşturulur ve her birinin avantajlarından yararlanılırken dezavantajları ortadan kalkar:
| Avantajlar | Dezavantajlar |
|---|---|
✅ GET veya POST ile erişilebilir | |
| ✅ Sunucuda veya CDN'de önbelleğe alınabilir | |
| ✅ Güvenlidir: yalnızca amaçlanan veriler açığa çıkar | |
| ✅ Veri eksik/fazla çekme sorunu yoktur | |
| ✅ Tüm veriler tek bir istekte alındığından hızlı olabilir | POST ile erişilebilir |
| ✅ Projenin hızlı iterasyonunu sağlar | |
| ✅ Kendi kendini belgeleyebilir | |
| ✅ Query için bir editör (GraphiQL) sağlar ve bu işi kolaylaştırır |
Persisted Query'yi Çalıştırma
Persisted query yayınlandıktan sonra kalıcı bağlantısı (permalink) aracılığıyla çalıştırabiliriz.
Persisted query, GET ile erişilebildiğinden doğrudan tarayıcıda çalıştırılabilir ve istenen veriler JSON formatında elde edilir:
Persisted Query Oluşturma
Menüdeki Persisted Queries bağlantısına tıklandığında, oluşturulan tüm persisted queries'in listesi görüntülenir:
Persisted query, özel bir gönderi türüdür (CPT). Yeni bir persisted query oluşturmak için "Yeni GraphQL persisted query ekle" düğmesine tıklayın; bu, WordPress editörünü açacaktır:
Ana giriş alanı, varsayılan olarak Explorer ile birlikte gelen GraphiQL istemcisidir. Sol yan paneldeki alanlara tıklamak bunları query'ye ekler ve "Run" düğmesine tıklamak query'yi çalıştırır:
Query hazır olduğunda yayınlayın; kalıcı bağlantısı endpoint'i haline gelir. Endpoint'e (ve kaynağa) ait bağlantı, "Persisted Query Endpoint Genel Bakış" kenar panelinde gösterilir:
Kalıcı bağlantıya ?view=source eklendiğinde, persisted query ve yapılandırması görüntülenir (kullanıcı oturum açmış ve kullanıcı rolünün erişim izni varsa):
Varsayılan olarak, persisted query'nin endpoint'i /graphql-query/ yoluna sahiptir ve bu değer Ayarlar üzerinden yapılandırılabilir:
Şema yapılandırması
Şemanın hangi öğeleri içerdiğini ve kullanıcıların şemaya hangi erişime sahip olacağını belirlemek, şema yapılandırmasında tanımlanır.
Bu nedenle bir şema yapılandırması oluşturmalı ve ardından açılır listeden seçmeliyiz:
Persisted Queries'i Kategoriye Göre Düzenleme
"Endpoint kategorileri" kenar panelinde Persisted Query'yi yönetmeye yardımcı olmak için kategoriler ekleyebiliriz:
Örneğin, endpoint'leri müşteri, uygulama veya gerekli başka herhangi bir bilgi parçasına göre yönetmek için kategoriler oluşturabiliriz:
Persisted Queries listesinde kategorilerini görebilir ve herhangi bir kategori bağlantısına tıklayarak veya üstteki filtreyi kullanarak yalnızca o kategoriye ait girişler görüntülenebilir:
Özel persisted queries
Persisted Query'nin durumu private olarak ayarlandığında, endpoint'e yalnızca yönetici kullanıcı erişebilir. Bu, verilerimizin erişmemesi gereken kullanıcılarla istemeden paylaşılmasını önler.
Örneğin, metriklerimizle raporlar oluşturmak için veri almak gibi uygulamayı yönetmeye yardımcı olan özel Persisted Queries oluşturabiliriz.
Parola korumalı persisted queries
Belirli bir müşteri için Persisted Query oluşturduğumuzda, yalnızca o müşterinin endpoint'e erişmesini sağlamak amacıyla ek bir güvenlik katmanı olarak parola atayabiliriz.
Parola korumalı bir persisted query'ye ilk kez erişildiğinde, parola isteyen bir ekranla karşılaşılır:
Parola sağlanıp doğrulandıktan sonra kullanıcı amaçlanan endpoint'e erişebilir.
URL parametreleriyle persisted query'yi dinamik hale getirme
Persisted query çalıştırılırken her değişkenin değeri, bir URL parametresiyle (değişken adıyla) ayarlanabilir. "URL parametreleri değişkenleri geçersiz kılar mı?" seçeneği etkinleştirilirse URL parametresi öncelikli olur. Aksi takdirde, değişkenler sözlüğünde tanımlanan değer öncelikli olur (varsa).
Örneğin, bu query'de sonuç sayısı varsayılan değeri 3 olan $limit değişkeniyle kontrol edilir:
Bu persisted query çalıştırılırken ?limit=5 parametresi geçirildiğinde query 5 sonuç döndürür:
