API tRPC

Vue d’ensemble

La plupart des données de Rolebase se lisent et s’écrivent via l’API GraphQL, qui reste la surface recommandée pour les intégrations. À côté, le backend expose une API tRPC : la couche RPC typée utilisée par l’application pour les opérations qui vont au-delà du simple CRUD, comme créer une organisation avec ses rôles de départ, archiver un rôle et ses descendants, exporter des données ou inviter un membre.

Cette section documente les procédures utiles depuis l’extérieur de l’application, à raison d’une page par routeur. Les procédures internes (webhooks, tâches planifiées, indexation de recherche) sont listées pour référence et ne sont pas destinées à être appelées directement.

Endpoint

L’API tRPC est servie à la racine du backend :

• Production : https://api.rolebase.io
• Développement local : http://localhost:8888

Elle suit le protocole HTTP standard de tRPC (requêtes en GET, mutations en POST), et fonctionne donc avec n’importe quel client tRPC ou en HTTP simple.

Authentification

Les procédures tRPC s’authentifient avec une clé API, la même que celle de l’API GraphQL. Créez-la depuis Paramètres > Clés API dans l’application et envoyez-la dans l’en-tête x-api-key :

x-api-key: <votre-cle-api>

Les procédures s’exécutent avec les permissions de l’utilisateur propriétaire de la clé. Quelques procédures sont publiques (lire une invitation ou une organisation partagée), et les procédures internes utilisent plutôt un secret de webhook.

Client typé

La façon la plus propre d’appeler l’API est un client tRPC typé qui importe le type du routeur depuis le package backend :

import { createTRPCClient, httpBatchLink } from '@trpc/client'
import type { AppRouter } from '@rolebase/backend'

const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'https://api.rolebase.io',
      headers: () => ({
        'x-api-key': apiKey,
      }),
    }),
  ],
})

// Requête
const data = await trpc.org.getPublicData.query({ orgId })

// Mutation
const { id } = await trpc.org.createOrg.mutate({ name: 'Acme', slug: 'acme' })

HTTP brut

Vous pouvez aussi appeler les procédures en HTTP simple, sans client tRPC.

# Requête : GET /<procedure>?input=<json-encode-url>
curl 'https://api.rolebase.io/org.getPublicData?input=%7B%22orgId%22%3A%22VOTRE_ORG_ID%22%7D' \
  -H 'x-api-key: VOTRE_CLE_API'

# Mutation : POST /<procedure> avec l’input en corps JSON
curl -X POST 'https://api.rolebase.io/circle.archiveCircle' \
  -H 'x-api-key: VOTRE_CLE_API' \
  -H 'Content-Type: application/json' \
  -d '{"circleId": "VOTRE_CIRCLE_ID"}'

La réponse est encapsulée sous la forme { "result": { "data": <valeur> } }.

Erreurs

Un appel en échec répond { "error": { "message": ..., "data": { "code": ..., "httpStatus": ... } } }, et un client typé lève une TRPCClientError portant le même code. Ces codes sont identiques pour toutes les procédures : les pages de référence ne signalent donc que ce qui est propre à une procédure.

Procédures

Les procédures sont regroupées en routeurs, et un appel combine le nom du routeur et celui de la procédure : org.createOrg, circle.archiveCircle.

Étapes suivantes

• Parcourez la référence de l’API GraphQL pour les entités, requêtes et mutations.
• Testez des requêtes en direct dans le Playground GraphQL.
• Configurez l’environnement de développement pour explorer le code du backend.