Esporre endpoint pubblici e privati
GraphQL si occupa tradizionalmente di esporre un singolo endpoint, di solito sotto https://mysite.com/graphql.
Gato GraphQL amplia questa nozione, permettendoci di esporre più endpoint personalizzati, ognuno adattato a un'esigenza specifica. Ad esempio, possiamo esporre endpoint:
/internale/public/apps/mobilee/apps/website/clientse/visitors/development,/staginge/production/teams/development,/teams/testinge/teams/marketing/clients/A,/clients/Beclients/Z- qualsiasi combinazione di questi
Gato GraphQL supporta anche le Persisted Queries, che sono endpoint in cui la query GraphQL è predefinita e memorizzata nel server.
Questa guida presenta suggerimenti su come e quando usare ciascun endpoint.
Oltre a proteggere gli endpoint dell'API Gato GraphQL, ti consigliamo di rafforzare sempre la sicurezza del tuo sito WordPress utilizzando un plugin di sicurezza dedicato, come WP Security Ninja.
Gli endpoint sono configurati tramite una Configurazione dello Schema, dove definiamo:
- Impostare lo schema come pubblico o privato
- Abilitare gli elementi di dati "sensibili"
- Applicare il namespacing allo schema
- Usare le mutation annidate
- Definire le intestazioni di risposta
- Concedere l'accesso agli elementi dello schema tramite Access Control List
- Configurare la cache HTTP
- Molti altri
Se abbiamo una configurazione che vogliamo applicare a tutti gli endpoint o alla maggior parte di essi, possiamo definire una Configurazione dello Schema predefinita.
Quando usare il singolo endpoint
Il singolo endpoint è sempre pubblico, esposto per impostazione predefinita sotto /graphql.
Gato GraphQL è gestito tramite "moduli", ognuno dei quali offre una funzionalità o un'estensione dello schema GraphQL, e che possono essere abilitati e disabilitati secondo necessità.
Per rafforzare la sicurezza della nostra API, è buona pratica disabilitare i moduli che estendono lo schema GraphQL (come i moduli "Posts", "Users", "Comments", "Blocks", ecc.) quando non sono necessari, per assicurarci che quei dati non vengano mai esposti in primo luogo.
In particolare, se l'API non è destinata a mutare dati (cioè creare o aggiornare risorse), è buona pratica disabilitare il modulo "Mutations". Così facendo, verranno a loro volta disabilitate tutte le estensioni che forniscono una mutation (come i moduli "Post Mutations", "Comment Mutations", ecc.), e queste mutation non verranno mai esposte nello schema GraphQL.
Il singolo endpoint è consigliato quando:
- Abbiamo bisogno di recuperare dati per alimentare una singola funzionalità, e
- Il sito WordPress non è accessibile da Internet pubblico (cioè gira su un computer di sviluppo, o dietro un firewall)
È il caso, ad esempio, della creazione di un sito headless (utilizzando Next.js, Gatsby, o altri).
Quando usare endpoint personalizzati pubblici
Gli endpoint personalizzati sono simili al singolo endpoint, ma possiamo averne molti, ognuno esposto sotto il proprio URL graphql/{custom-endpoint-slug}/, ciascuno con una configurazione diversa.
Gli endpoint personalizzati offrono sicurezza tramite oscurità, poiché solo il destinatario previsto dovrebbe conoscere l'esistenza dell'endpoint personalizzato e il suo URL.
Per rafforzare la sicurezza dell'API, possiamo usare l'estensione Access Control per concedere l'accesso all'endpoint solo quando:
- L'utente è connesso (o no)
- L'utente ha un certo ruolo
- L'utente ha una certa capability
- Il visitatore proviene da un IP consentito (tramite l'estensione Access Control: Visitor IP)
Ogni endpoint personalizzato può avere la propria Access Control List, risultando così accessibile solo dal suo specifico utente previsto.
Gli endpoint personalizzati sono consigliati quando dobbiamo gestire e personalizzare gli accessi all'API, che sia da parte di diverse applicazioni, team, clienti, o altro.
Quando usare endpoint personalizzati privati
Gato GraphQL implementa gli endpoint personalizzati tramite Custom Post Type (CPT). Questo ci permette di pubblicare l'endpoint personalizzato come privato (e anche come protetto da password), rendendo così l'endpoint personalizzato accessibile solo agli utenti connessi che hanno il diritto di accedere a quel post personalizzato, e a nessun altro.
Questo metodo è consigliato quando l'endpoint GraphQL è destinato a essere usato solo dall'amministratore del sito (come quando si usa GraphQL per eseguire attività di amministrazione). Bloccando completamente l'accesso all'endpoint dai visitatori esterni, rafforzeremo la sicurezza del sito.
Quando usare le Persisted Queries pubbliche
Le persisted queries sono endpoint, ognuno con il proprio URL, ma la query GraphQL è già definita lato server, quindi anche la risposta è predefinita (può essere resa dinamica definendo variabili, da soddisfare tramite parametri URL).
Le persisted queries sono simili agli endpoint REST, ma usiamo il linguaggio GraphQL per comporre la query, e possiamo pubblicarla direttamente da wp-admin. Non è necessario distribuire alcun codice PHP per pubblicare una persisted query.
Poiché le persisted queries non richiedono di passare la query GraphQL nel corpo della richiesta, sono naturalmente adatte a essere accedute tramite GET invece di POST.
(Il singolo endpoint e gli endpoint personalizzati possono anche essere acceduti tramite GET aggiungendo il parametro ?query={ GraphQL query } all'endpoint.)
Possiamo trarne vantaggio e rendere l'API più veloce tramite la cache HTTP standard, mettendo in cache la risposta GraphQL lato client o nelle fasi intermedie tra il client e il server (come una CDN).
Ciò si ottiene tramite l'estensione Cache Control, che calcola ed emette automaticamente il valore max-age della risposta in base ai campi e alle direttive presenti nella query.
Si consiglia di usare le persisted queries ogni volta che è possibile, poiché aumentano notevolmente la sicurezza dei nostri siti.
Questo perché tutti i dati che devono essere resi disponibili per la nostra applicazione possono già essere esposti tramite persisted queries. Poi possiamo evitare di esporre il singolo endpoint GraphQL (o qualsiasi endpoint personalizzato), eliminando così la possibilità che gli utenti possano accedere a dati privati che abbiamo lasciato esposti (per errore o altrimenti).
Quando usare le Persisted Queries private
Similmente agli endpoint personalizzati, le persisted queries sono CPT, quindi possiamo pubblicarle come private (o protette da password), rendendole accessibili solo agli utenti connessi che hanno il diritto di accedervi, e a nessun altro.
Si consiglia di usarle ogni volta che la query è destinata solo a un uso interno, come quando si cercano dati WordPress per il nostro uso.