Exposer des endpoints publics et privés
GraphQL traite traditionnellement de l'exposition d'un endpoint unique, généralement sous https://mysite.com/graphql.
Gato GraphQL élargit cette notion, nous permettant d'exposer plusieurs endpoints personnalisés, chacun adapté à un besoin spécifique. Par exemple, nous pouvons exposer des endpoints :
/internalet/public/apps/mobileet/apps/website/clientset/visitors/development,/staginget/production/teams/development,/teams/testinget/teams/marketing/clients/A,/clients/Betclients/Z- toute combinaison de ceux-ci
Gato GraphQL prend également en charge les Requêtes Persistées, qui sont des endpoints où la requête GraphQL est prédéfinie et stockée sur le serveur.
Ce guide présente des suggestions sur comment et quand utiliser chaque endpoint.
En plus de sécuriser vos endpoints d'API Gato GraphQL, nous vous recommandons de toujours renforcer la sécurité de votre site WordPress en utilisant un plugin de sécurité dédié, comme WP Security Ninja.
Les endpoints sont configurés via une Configuration du Schéma, où nous définissons :
- Définir le schéma comme public ou privé
- Activer les éléments de données « sensibles »
- Appliquer le namespacing au schéma
- Utiliser les mutations imbriquées
- Définir les en-têtes de réponse
- Accorder l'accès aux éléments du schéma via des listes de contrôle d'accès
- Configurer la mise en cache HTTP
- Bien d'autres
Si nous avons une configuration que nous souhaitons appliquer à tous les endpoints ou à la plupart d'entre eux, nous pouvons définir une Configuration du Schéma par défaut.
Quand utiliser l'endpoint unique
L'endpoint unique est toujours public, exposé par défaut sous /graphql.
Gato GraphQL est géré via des « modules », chacun offrant une fonctionnalité ou une extension du schéma GraphQL, et qui peuvent être activés et désactivés selon les besoins.
Pour renforcer la sécurité de notre API, il est recommandé de désactiver les modules qui étendent le schéma GraphQL (comme les modules « Posts », « Users », « Comments », « Blocks », etc.) lorsqu'ils ne sont pas nécessaires, afin de s'assurer que ces données ne seront jamais exposées en premier lieu.
En particulier, si l'API n'est pas destinée à muter des données (c'est-à-dire créer ou mettre à jour des ressources), il est recommandé de désactiver le module « Mutations ». Ce faisant, toutes les extensions fournissant une mutation seront à leur tour désactivées (comme les modules « Post Mutations », « Comment Mutations », etc.), et ces mutations ne seront jamais exposées dans le schéma GraphQL.
L'endpoint unique est recommandé lorsque :
- Nous avons besoin de récupérer des données pour alimenter une seule fonctionnalité, et
- Le site WordPress n'est pas accessible à l'Internet public (c'est-à-dire qu'il tourne sur un ordinateur de développement, ou derrière un pare-feu)
C'est le cas, par exemple, pour construire un site headless (en utilisant Next.js, Gatsby, ou d'autres).
Quand utiliser des endpoints personnalisés publics
Les endpoints personnalisés sont similaires à l'endpoint unique, mais nous pouvons en avoir plusieurs, chacun exposé sous sa propre URL graphql/{custom-endpoint-slug}/, chacun ayant une configuration différente.
Les endpoints personnalisés offrent une sécurité par l'obscurité, car seule la cible visée devrait connaître l'existence de l'endpoint personnalisé et son URL.
Pour renforcer la sécurité de l'API, nous pouvons utiliser l'extension Access Control pour accorder l'accès à l'endpoint uniquement lorsque :
- L'utilisateur est connecté (ou non)
- L'utilisateur a un certain rôle
- L'utilisateur a une certaine capacité
- Le visiteur provient d'une IP autorisée (via l'extension Access Control: Visitor IP)
Chaque endpoint personnalisé peut avoir sa propre liste de contrôle d'accès, étant ainsi accessible uniquement par son utilisateur spécifique prévu.
Les endpoints personnalisés sont recommandés lorsque nous devons gérer et personnaliser les accès à l'API, que ce soit par différentes applications, équipes, clients, ou tout autre.
Quand utiliser des endpoints personnalisés privés
Gato GraphQL implémente les endpoints personnalisés via des Custom Post Types (CPTs). Cela nous permet de publier l'endpoint personnalisé comme privé (et également comme protégé par mot de passe), rendant ainsi l'endpoint personnalisé accessible uniquement aux utilisateurs connectés qui ont le droit d'accéder à ce post personnalisé, et à personne d'autre.
Cette méthode est recommandée lorsque l'endpoint GraphQL est destiné à être utilisé uniquement par l'administrateur du site (comme lors de l'utilisation de GraphQL pour exécuter des tâches d'administration). En bloquant complètement l'accès à l'endpoint depuis l'extérieur, nous renforcerons la sécurité du site.
Quand utiliser des Requêtes Persistées publiques
Les requêtes persistées sont des endpoints, chacun ayant sa propre URL, mais la requête GraphQL est déjà définie côté serveur, et la réponse est donc également prédéfinie (elle peut être rendue dynamique en définissant des variables, à satisfaire par des paramètres d'URL).
Les requêtes persistées sont similaires aux endpoints REST, mais nous utilisons le langage GraphQL pour composer la requête, et nous pouvons la publier directement depuis wp-admin. Il n'est pas nécessaire de déployer du code PHP pour publier une requête persistée.
Comme les requêtes persistées ne nécessitent pas de passer la requête GraphQL dans le corps de la requête, elles sont naturellement adaptées à un accès via GET plutôt que POST.
(L'endpoint unique et les endpoints personnalisés peuvent également être accédés via GET en ajoutant le paramètre ?query={ GraphQL query } à l'endpoint.)
Nous pouvons en bénéficier et rendre l'API plus rapide via la mise en cache HTTP standard, en mettant en cache la réponse GraphQL côté client ou dans les étapes intermédiaires entre le client et le serveur (comme un CDN).
Cela est accompli via l'extension Cache Control, qui calcule et émet automatiquement la valeur max-age de la réponse en fonction des champs et directives présents dans la requête.
Il est recommandé d'utiliser les requêtes persistées dans la mesure du possible, car elles augmentent considérablement la sécurité de nos sites.
En effet, toutes les données devant être disponibles pour notre application peuvent déjà être exposées via des requêtes persistées. Ensuite, nous pouvons éviter d'exposer l'endpoint unique GraphQL (ou tout endpoint personnalisé), éliminant ainsi la possibilité que des utilisateurs puissent accéder à des données privées que nous avons laissées exposées (par erreur ou autrement).
Quand utiliser des Requêtes Persistées privées
Similaires aux endpoints personnalisés, les requêtes persistées sont des CPTs, nous pouvons donc les publier comme privées (ou protégées par mot de passe), les rendant accessibles uniquement aux utilisateurs connectés qui ont le droit d'y accéder, et à personne d'autre.
Il est recommandé de les utiliser lorsque la requête est destinée à un usage interne uniquement, comme lors de la recherche de données WordPress pour notre propre usage.