This page guides you through the process of making you first API call to the Elium API without going into too much details.

The Elium API uses GraphQL as language to query and modify data.

In this guide, we use the free and open-source tool Insomnia to make API calls. We advise you to install it to explore and familiarize yourself with the API. After that, you can use any compatible library or use any HTTP client you are familiar with.

Authentication

The Elium API uses OAuth 2.0 to enable an application to make calls on behalf of an Elium user. You will need to set up a connected app in Elium, and use this app to make API calls.

In Elium:

• In the settings, go to the Security tab, then scroll to the section Connected apps
• Click on New application
• Enter a name, a redirect URL, and tick the box 'trusted'.

The newly create connected app will appear in the list below. You will need the client credentials listed there to configure your application.

In Insomnia, create a new request:

Select the method POST, and select GraphQL as body type.

In the Auth Tab, select the option OAuth 2.0.

Finally, configure the following parameters:

Endpoint: https://my-platform.elium.com/graphql
Authorization URL: https://my-platform.elium.com/oauth/authorize
Access token URL: https://my-platform.elium.com/oauth/token
Redirect URL: The redirect URL of your connected app
Client ID: The Id of your connected app
Client secret: The Secret of your connected app
Scopes: apiv1

Insomnia will handle the complexity of the OAuth flow for you. The following page goes through the OAuth flow in more details.

At this stage, your configuration should look like this:

Clicking on fetch tokens will prompt an Elium login page. Enter your credentials, and you will receive OAuth tokens.

Now that you have access tokens, you may start performing API calls to your Elium platform !

Let's make sure you are authenticated by running a simple query: retrieving the current user id. If you are using Insomnia, just paste the following in the GraphQL body and click "Send".

graphql
query {
    me {
        id
    }
}

If everything went well in the previous steps, you should see the result of the request, which looks like this (with a different id)

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

Responses are always in json, and the results under a "data" key.

Retrieving your first story

Let's make things a bit more interesting by querying our first story.

To identify the story we want to query, we'll use it's slug. The slug is visible in the url of a story. For example, if the story is accessed at https://my-platform.elium.com/tile/view/123/, then the slug is 123

Use the following GraphQL body to query a story, and retrieve its title and the name of its owner. Just replace the slug in the example with the one of a story from your platform.

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

The response should look like this:

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

Where to go now?

The authentication section covers in more detail the OAuth flow that you will need to setup to make API calls with the tools of your choice.