Extension GraphQL

Installer et explorer#

Activez bracten.graphql puis ouvrez API GraphQL dans les espaces d’extensions avec bracten.graphql.manage. L’explorateur privé affiche le schéma et les résultats. Il utilise les mêmes règles de visibilité que l’API publique ; un administrateur ne voit pas automatiquement les contenus réservés d’un groupe.

Schéma actuel#

type Content {
  id: ID!
  type: String!
  title: String!
  slug: String!
  excerpt: String!
  publishedAt: String
}
type ContentPage { items: [Content!]!, total: Int!, limit: Int!, offset: Int! }
type Query {
  content(id: ID, slug: String): Content
  contents(type: String, search: String, limit: Int = 20, offset: Int = 0): ContentPage!
}

content exige exactement id ou slug. contents filtre avant pagination et total. Les blocs, champs personnalisés, comptes, réglages, brouillons et contenus non publiés ne sont pas exposés.

Requête depuis l’origine du site#

const base = "/api/v1/public-extensions/bracten.graphql";
const tokenResponse = await fetch(base + "/token");
if (!tokenResponse.ok) throw new Error("Token request failed");
const { token } = await tokenResponse.json();
const response = await fetch(base + "/endpoints/query", {
  method: "POST",
  credentials: "same-origin",
  headers: { "content-type": "application/json", "x-bracten-public-token": token },
  body: JSON.stringify({
    query: "{ contents(limit: 10) { total items { id title slug } } }",
  }),
});
if (!response.ok) throw new Error("GraphQL request refused");
const result = await response.json();

GET /endpoints/read accepte query, variables JSON et operationName dans la query string. POST /endpoints/query exige Origin exact et jeton expirant. Une session facultative applique les groupes du membre ; un cookie expiré revient à une lecture anonyme. Aucun token d’administration ne doit être exposé dans un client public.

Limites et erreurs#

Les bornes sont 8 000 caractères de requête, 1 000 tokens, 60 champs, six niveaux, une opération, 50 éléments par page et offset maximal 100 000. Les variables sérialisées sont limitées à 8 000 caractères. Mutations, souscriptions, fragments nommés et introspection sont refusés.

Les erreurs de syntaxe et de validation GraphQL utilisent errors ; une protection HTTP peut retourner une erreur REST et un statut non 200. Le client doit vérifier les deux. Cette API ne remplace pas encore un schéma headless complet ou une API d’écriture.