Skip to main content

GraphQL API

GraphQL is a query language for APIs. You can use it to request the exact data you need, and therefore limit the number of requests you need.

GraphQL data is arranged in types, so your client can use client-side GraphQL libraries to consume the API and avoid manual parsing.

The GraphQL API is versionless.

Accessing GraphIQL​

The easiest way to use the GraphQL API is through GraphIQL using the following steps.

  1. Sign into IRIDA Next http://my.irida.server/users/sign_in
  2. Go to the GraphIQL url http://my.irida.server/graphiql

You will be greeted with the in browser tool for writing, validating and testing GraphQL queries.

For more on GraphIQL see the official docs

GraphQL Examples​

Example Query Response
Get Current User 
query {
  currentUser {
    email
  }
}
{
  "data": {
    "currentUser": {
      "email": "admin@email.com"
    }
  }
}
Get Samples 
query {
  samples (first:5){
    nodes{
      name
      id
    }
  }
}
{
  "data": {
    "samples": {
      "nodes": [
        {
          "name": "Bacillus anthracis/Outbreak 2022 Sample 1",
          "id": "gid://irida/Sample/1"
        },
        {
          "name": "Bacillus anthracis/Outbreak 2022 Sample 2",
          "id": "gid://irida/Sample/2"
        },
        {
          "name": "Bacillus anthracis/Outbreak 2022 Sample 3",
          "id": "gid://irida/Sample/3"
        },
        {
          "name": "Bacillus anthracis/Outbreak 2022 Sample 4",
          "id": "gid://irida/Sample/4"
        },
        {
          "name": "Bacillus anthracis/Outbreak 2022 Sample 5",
          "id": "gid://irida/Sample/5"
        }
      ]
    }
  }
}
Get a specific samples details 
query {
  node(id: "gid://irida/Sample/1"){
    ... on Sample{
      id,
      name
      description
      metadata
      project{
        id,
        fullPath
      }
    }
  }
}
{
  "data": {
    "node": {
      "id": "gid://irida/Sample/1",
      "name": "Bacillus anthracis/Outbreak 2022 Sample 1",
      "description": "This is a description for sample Bacillus anthracis/Outbreak 2022 Sample 1.",
      "project": {
        "id": "gid://irida/Project/1",
        "fullPath": "bacillus/bacillus-anthracis/outbreak-2022"
      },
      "metadata": {
        "age": 40,
        "food": "Cheeseburger",
        "onset": "2022-06-21",
        "WGS_id": 6862301436,
        "gender": "Female",
        "country": "Gabon",
        "patient_age": 8,
        "patient_sex": "Male",
        "earliest_date": "2022-10-03",
        "NCBI_ACCESSION": "NM_7807606.5"
      }
    }
  }
}

Authentication with Personal Access Tokens​

To use the GraphQL API with any of the GraphQL Clients, you will need to generate a Personal Access Token.

Once you are signed in to IRIDA Next follow these steps.

  1. From the top bar on the left sidebar, select the Profile Icon next to the plus sign
  2. From the drop down options, select Edit profile
  3. From the left sidebar, select Access Tokens

This page lets you add new personal access tokens, and view/remove existing tokens.

Token Scopes​

There are 2 scopes for your access token, api and read_api

If your GraphQL queries will only be reading data, and not making any changes, select read_api.

If your GraphQL queries will be modifying data or uploading new data, select api.

Generate a Token​

When Create personal access token is clicked, a secret token will be generated for you. This will be used to authenticate your GraphQL API requests.

It is important that you do not share this token with anyone else as it is directly tied to your account.

Using Token for Sessionless Authentication​

Tokens generated by IRIDA Next are Basic Authentication tokens. They are tied to your email.

This uses Basic HTTP Authentication, in the form of $USEREMAIL:$ACCESSTOKEN that is Base64 encoded.

e.g. admin@email.com:yK1euURqVRtQ1D-3uKsW becomes YWRtaW5AZW1haWwuY29tOnlLMWV1VVJxVlJ0UTFELTN1S3NX

Which would be used like the following:

e.g. Authorization: Basic YWRtaW5AZW1haWwuY29tOnlLMWV1VVJxVlJ0UTFELTN1S3NX

You can test your token by doing the encoding and executing the following curl command.

curl "http://localhost:3000/api/graphql" --header "Authorization: Basic <your token here>" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {currentUser{email}}}\"}"

response

{"data":{"currentUser":{"email":"admin@email.com"}}}