À propos de l’API
L’API d’Elium est une API GraphQL : ce qu’elle couvre, les noms qu’elle utilise, où trouver la référence et comment lire ces guides.
Une seule adresse, un seul langage
L’API d’Elium est une API GraphQL. Chaque requête et chaque mutation passe par la même adresse :
https://nom-de-votre-plateforme.elium.com/graphql
Avec GraphQL, vous demandez exactement les champs dont vous avez besoin, et rien d’autre, en une seule requête. Vous décrivez la forme de la réponse, et le serveur renvoie un document JSON de cette forme sous une clé data.
Vous pouvez l’appeler avec n’importe quel client HTTP ou n’importe quelle bibliothèque GraphQL. Ces guides utilisent Insomnia, un client de bureau gratuit, parce qu’il gère la connexion et affiche le schéma pendant que vous écrivez.
Comment un programme se connecte
Un programme s’authentifie avec OAuth 2.0, en tant qu’application connectée, qu’un administrateur système enregistre une fois dans "Paramètres" > "Avancé" > "Applications connectées". L’application reçoit un identifiant client et un secret client, et chaque utilisateur l’approuve avant qu’elle n’agisse en son nom. L’enregistrement est décrit dans API et applications connectées, l’échange de jetons dans Authentification.
Les assistants IA comme ChatGPT ou Claude n’ont pas besoin de l’API : Elium propose aussi un serveur Model Context Protocol (MCP), auquel ces assistants se connectent sans aucun code. Consultez À propos de MCP.
Le vocabulaire de l’API
L’API a gardé les noms qu’Elium utilisait à ses débuts. L’interface en a renommé certains depuis.
| Dans l’API | Dans l’interface |
|---|---|
Story | Article |
StorySchema | Modèle |
Facet | Catégorie (une famille de tags) |
Instance | Plateforme |
Ces guides disent "story" quand ils parlent de l’objet de l’API, parce que c’est le mot que vous allez taper.
Où chercher
- La référence GraphQL liste chaque type, requête et mutation, avec ses champs et ses arguments.
- Votre plateforme se décrit elle-même. Les clients GraphQL lisent le schéma par introspection : Insomnia complète les noms de champs pendant que vous écrivez et affiche la documentation de chacun.
- Format Markdown en entrée décrit le Markdown qu’Elium importe, l’un des formats que l’API accepte pour le corps d’une story.
Comment lire ces guides
- Premiers pas vous mène d’une application connectée à votre première requête (Démarrage rapide). Cette partie détaille ensuite les flux OAuth (Authentification) et la seule notion GraphQL à connaître avant tout le reste (Identifiants GraphQL et nœuds).
- Concepts principaux décrit les objets et leurs relations (Stories, espaces et utilisateurs), puis la façon dont les mutations signalent un problème (Erreurs).
- Guides pratiques donne un exemple complet pour chaque action courante, de la lecture d’une story à une question posée à Elium Answer.