Elium

APIPremiers pas

Démarrage rapide

Faites votre premier appel à l’API d’Elium avec Insomnia : enregistrez une application connectée, obtenez un jeton et lisez une story.

Ce guide vous mène à votre premier appel à l’API sans entrer dans les détails. Il utilise Insomnia, un client de bureau gratuit, pour se connecter et envoyer des requêtes. Une fois ce premier appel réussi, vous pourrez passer à n’importe quelle bibliothèque GraphQL ou n’importe quel client HTTP.

Enregistrer une application connectée

L’API utilise OAuth 2.0 : un programme appelle Elium au nom d’un utilisateur. Dans Elium, ce programme est une application connectée.

  1. Cliquez sur votre avatar, choisissez "Paramètres", puis "Avancé" > "Applications connectées".
  2. Cliquez sur "Nouvelle application".
  3. Saisissez un titre, une URL de redirection comme http://localhost:8080/ et cochez le droit "API". Insomnia intercepte lui-même la redirection : l’adresse n’a pas besoin d’exister.
  4. Activez "De confiance" si vous ne voulez pas approuver l’application à chaque connexion, puis enregistrez.

L’application apparaît dans la liste avec son identifiant client et son secret client. Vous aurez besoin des deux à l’étape suivante.

API et applications connectées décrit toutes les options : plusieurs URL de redirection, les droits et les applications de confiance.

Configurer Insomnia

Dans Insomnia, créez une nouvelle requête et choisissez le type GraphQL.

Dans l’onglet "Auth", sélectionnez "OAuth 2.0".

Remplissez les champs :

Grant type:           Authorization Code
URL:                  https://nom-de-votre-plateforme.elium.com/graphql
Authorization URL:    https://nom-de-votre-plateforme.elium.com/oauth/authorize
Access token URL:     https://nom-de-votre-plateforme.elium.com/oauth/token
Redirect URL:         the redirect URL of your connected app
Client ID:            the client ID of your connected app
Client secret:        the client secret of your connected app
Scope:                apiv1 (under Advanced Options)

Cochez "Use PKCE" (Proof Key for Code Exchange) et gardez la méthode SHA-256. Elium accepte PKCE pour toute application et l’exige pour une application sans secret client.

Cliquez sur "Fetch tokens". Insomnia ouvre la page de connexion d’Elium. Connectez-vous, puis approuvez l’application si Elium vous le demande. Insomnia conserve les jetons.

Authentification explique ce qu’Insomnia vient de faire, pour le jour où vous intégrerez ce flux à votre propre programme.

Votre première requête

Vérifiez que vous êtes connecté en récupérant l’utilisateur courant. Collez ceci dans le corps GraphQL et cliquez sur "Send" :

query {
  me {
    id
  }
}

La réponse est en JSON, avec le résultat sous une clé data :

{
  "data": {
    "me": {
      "id": "TWU6MTIz"
    }
  }
}

Lire une story

Dans l’API, un article est une story. Pour en trouver une, utilisez son slug, le numéro qui figure dans son adresse : dans https://nom-de-votre-plateforme.elium.com/tile/view/123/, le slug est 123.

Remplacez le slug par celui d’une story de votre plateforme et envoyez :

query {
  story(slug: 123) {
    slug
    version {
      title
    }
    user {
      name
    }
  }
}

La réponse donne le titre de la dernière version et le nom du propriétaire :

{
  "data": {
    "story": {
      "slug": 123,
      "version": {
        "title": "My first story"
      },
      "user": {
        "name": "John Doe"
      }
    }
  }
}

Vous pouvez demander autant de champs et de sous-champs que nécessaire. Insomnia complète les noms de champs à mesure que vous tapez, et son bouton de schéma affiche la documentation de chacun.

Pour aller plus loin