Elium

APIGetting started

Quick start

Make your first call to the Elium API with Insomnia: register a connected app, get a token and query a story.

This guide takes you to your first API call without going into detail. It uses Insomnia, a free desktop client, to sign in and send queries. Once it works, you can use any GraphQL library or HTTP client.

Register a connected app

The API uses OAuth 2.0: a program calls Elium on behalf of a user. In Elium, that program is a connected app.

  1. Click your avatar, choose Settings, then select Advanced > Connected apps.
  2. Click New application.
  3. Enter a title, a redirect URL such as http://localhost:8080/, and tick the API scope. Insomnia catches the redirect itself, so the address does not need to exist.
  4. Tick Trusted if you do not want to approve the app on each sign-in, then save.

The app appears in the list with its client ID and client secret. You need both in the next step.

API and connected applications describes all the options: several redirect URLs, scopes and trusted apps.

Configure Insomnia

In Insomnia, create a new request and choose the GraphQL type.

In the Auth tab, select OAuth 2.0.

Fill in the fields:

Grant type:           Authorization Code
URL:                  https://your-platform-name.elium.com/graphql
Authorization URL:    https://your-platform-name.elium.com/oauth/authorize
Access token URL:     https://your-platform-name.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)

Tick Use PKCE (Proof Key for Code Exchange) and keep the SHA-256 method. Elium accepts PKCE from every application and requires it from an application that has no client secret.

Click Fetch tokens. Insomnia opens the Elium sign-in page. Sign in, approve the app if it asks you to, and Insomnia stores the tokens.

Authentication explains what Insomnia just did, for when you build the flow into your own program.

Your first query

Check that you are signed in by asking for the current user. Paste this in the GraphQL body and click Send:

query {
  me {
    id
  }
}

The response is JSON, with the result under a data key:

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

Read a story

In the API, an article is a story. To find one, use its slug, the number in its address: for https://your-platform-name.elium.com/tile/view/123/, the slug is 123.

Replace the slug with one from your platform and send:

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

The response gives the title of the latest version and the name of the owner:

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

You can ask for as many fields and sub-fields as you need. Insomnia completes field names as you type, and its schema button shows the documentation of each one.

Where to go now