Genel ve özel endpointleri yayınlama
GraphQL geleneksel olarak tek bir endpoint yayınlamakla ilgilidir; genellikle https://mysite.com/graphql altında.
Gato GraphQL bu kavramı genişletir ve her biri belirli bir ihtiyaca göre özelleştirilmiş birden fazla özel endpoint yayınlamamıza olanak tanır. Örneğin şu endpointleri yayınlayabiliriz:
/internalve/public/apps/mobileve/apps/website/clientsve/visitors/development,/stagingve/production/teams/development,/teams/testingve/teams/marketing/clients/A,/clients/Bveclients/Z- bunların herhangi bir kombinasyonu
Gato GraphQL ayrıca Persisted Queries'i destekler; bunlar, GraphQL query'sinin önceden tanımlandığı ve sunucuda depolandığı endpointlerdir.
Bu kılavuz, her bir endpointin nasıl ve ne zaman kullanılacağına dair öneriler sunar.
Gato GraphQL API endpointlerinizi güvence altına almanın yanı sıra, WordPress sitenizin güvenliğini her zaman WP Security Ninja gibi özel bir güvenlik eklentisi kullanarak sıkılaştırmanızı öneririz.
Endpointler bir Şema Yapılandırması aracılığıyla yapılandırılır; burada şunları tanımlarız:
- Şemayı genel veya özel olarak ayarlama
- "Hassas" veri öğelerini etkinleştirme
- Şemayı ad alanıyla belirleme
- İç içe mutations kullanma
- Yanıt başlıklarını tanımlama
- Access Control List'leri aracılığıyla şema öğelerine erişim verme
- HTTP önbelleklemesini ayarlama
- Ve daha fazlası
Tüm veya çoğu endpointe uygulamak istediğimiz bir yapılandırmamız varsa, varsayılan bir Şema Yapılandırması tanımlayabiliriz.
Tek endpoint ne zaman kullanılır
Tek endpoint her zaman geneldir ve varsayılan olarak /graphql altında yayınlanır.
Gato GraphQL, her biri GraphQL şemasının bir işlevselliğini veya uzantısını sunan ve gerektiğinde etkinleştirip devre dışı bırakılabilen "modüller" aracılığıyla yönetilir.
API'mizin güvenliğini sıkılaştırmak için, GraphQL şemasını genişleten modülleri (örneğin "Posts", "Users", "Comments", "Blocks" vb. modüller) gerekli olmadıklarında devre dışı bırakmak iyi bir uygulamadır; böylece bu verilerin hiçbir zaman yayınlanmamasını sağlarız.
Özellikle API veri mutasyonu (yani kaynak oluşturma veya güncelleme) için kullanılmayacaksa, "Mutations" modülünü devre dışı bırakmak iyi bir uygulamadır. Bunu yapmak, bazı mutation sağlayan tüm uzantıları ("Post Mutations", "Comment Mutations" vb. modüller gibi) devre dışı bırakır ve bu mutations'lar GraphQL şemasında hiçbir zaman yayınlanmaz.
Tek endpoint şu durumlarda önerilir:
- Tek bir özelliği desteklemek için veri almamız gerektiğinde ve
- WordPress web sitesine açık İnternet'ten erişilemediğinde (yani geliştirme bilgisayarında çalışıyorsa veya bir güvenlik duvarının arkasındaysa)
Bu durum, örneğin headless bir site oluşturma (Next.js, Gatsby veya diğerlerini kullanarak) için geçerlidir.
Genel özel endpointler ne zaman kullanılır
Özel endpointler tek endpointe benzer, ancak her biri kendi URL'si graphql/{custom-endpoint-slug}/ altında yayınlanan ve her biri farklı bir yapılandırmaya sahip olan birden fazla endpointe sahip olabiliriz.
Özel endpointler, belirsizlik yoluyla güvenlik sağlar; çünkü yalnızca hedeflenen kişinin özel endpointin varlığından ve URL'sinden haberdar olması beklenir.
API'nin güvenliğini sıkılaştırmak için, yalnızca şu durumlarda endpointe erişim vermek amacıyla Access Control uzantısını kullanabiliriz:
- Kullanıcı oturum açmışsa (veya açmamışsa)
- Kullanıcının belirli bir rolü varsa
- Kullanıcının belirli bir yetkisi varsa
- Ziyaretçi izin verilen bir IP'den geliyorsa (Access Control: Visitor IP uzantısı aracılığıyla)
Her özel endpoint kendi Access Control List'ine sahip olabilir ve böylece yalnızca belirli hedeflenen kullanıcı tarafından erişilebilir olur.
Özel endpointler, farklı uygulamalar, ekipler, müşteriler veya diğerleri tarafından API'ye erişimi yönetmemiz ve özelleştirmemiz gerektiğinde önerilir.
Özel özel endpointler ne zaman kullanılır
Gato GraphQL, özel endpointleri Custom Post Type'lar (CPT'ler) aracılığıyla uygular. Bu, özel endpointi private olarak yayınlamamıza (ve ayrıca password-protected olarak da) olanak tanır; böylece özel endpoint yalnızca o özel gönderiye erişim hakkına sahip oturum açmış kullanıcılar tarafından erişilebilir olur, başka kimse erişemez.
Bu yöntem, GraphQL endpointinin yalnızca site yöneticisi tarafından kullanılması amaçlandığında önerilir (örneğin yönetici görevlerini gerçekleştirmek için GraphQL kullanıldığında). Dışarıdan ziyaretçilerin endpointe erişimini tamamen engelleyerek sitenin güvenliğini sıkılaştırmış oluruz.
Genel Persisted Queries ne zaman kullanılır
Persisted queries, her biri kendi URL'sine sahip endpointlerdir; ancak GraphQL query'si sunucu tarafında zaten tanımlanmıştır, dolayısıyla yanıt da önceden belirlenmiştir (URL parametreleriyle karşılanacak değişkenler tanımlanarak dinamik hale getirilebilir).
Persisted queries, REST endpointlerine benzer; ancak query'yi oluşturmak için GraphQL dilini kullanırız ve bunu doğrudan wp-admin'den yayınlayabiliriz. Bir persisted query yayınlamak için herhangi bir PHP kodu dağıtmaya gerek yoktur.
Persisted queries, isteğin gövdesinde GraphQL query'sinin geçirilmesini gerektirmediğinden, doğal olarak POST yerine GET aracılığıyla erişime uygundur.
(Tek endpoint ve özel endpointlere de ?query={ GraphQL query } parametresi eklenerek GET aracılığıyla erişilebilir.)
Bundan yararlanarak standart HTTP Önbelleklemesi aracılığıyla API'yi daha hızlı hale getirebiliriz; GraphQL yanıtını istemci tarafında veya istemci ile sunucu arasındaki ara aşamalarda (CDN gibi) önbellekleyebiliriz.
Bu, Cache Control uzantısı aracılığıyla gerçekleştirilir; uzantı, query'de bulunan alan adlarına ve direktiflere göre yanıtın max-age değerini otomatik olarak hesaplar ve çıkarır.
Sitelerimizin güvenliğini önemli ölçüde artırdıkları için mümkün olan her durumda persisted queries kullanılması önerilir.
Bunun nedeni, uygulamamız için erişilebilir kılınması gereken tüm verilerin persisted queries aracılığıyla zaten yayınlanabilmesidir. Böylece GraphQL tek endpointini (veya herhangi bir özel endpointi) yayınlamayı atlayabiliriz; bu da kullanıcıların (hata veya başka nedenlerle) yayınlanmış olarak bıraktığımız özel verilere erişme ihtimalini ortadan kaldırır.
Özel Persisted Queries ne zaman kullanılır
Özel endpointlere benzer şekilde, persisted queries de CPT'lerdir; dolayısıyla bunları private (veya password-protected) olarak yayınlayabiliriz; böylece yalnızca erişim hakkına sahip oturum açmış kullanıcılar tarafından erişilebilir olurlar, başka kimse erişemez.
Query yalnızca dahili kullanım için tasarlandığında, örneğin kendi kullanımımız için WordPress verilerini ararken, bunların kullanılması önerilir.