Skip to content

Explore the GraphQL API

In this guide we will help you to understand, navigate and query the API. We will give you examples in GraphQL syntax, raw JSON format and PowerShell syntax for you to copy and paste to your preferred tool for querying a GraphQL API.

Basics

All requests are sent as an HTTP POST request (Insomnia and GraphQL request in Postman abstracts this for you). Authentication is done by sending an Easit GO API-key as a bearer token. GraphQL provides it own id for everything from modules, item types, items, file entries and so on. In GraphQL, an item is what we in Easit GO terms think of as contacts, organizations, requests, assets and so.

Schema documentation

The GraphQL schema declares what you can "do" with the API. Some tools, like Insomnia, offer a way to read the schema documentation directly in the tool itself. If you are not using such a tool, you can find the documentation here:

Your first query

Let us start by querying your instance of Easit GO for all available modules. Let us take a closer look at the query operation page, and more specifically at the query operation modules we can see that the operation do not take any arguments and its return type is module. From the return type specification we can see that it has the following fields that is of interest for us now.

  • id - The id for this module
  • name - The name for this module

We now have the information we need to query the API for all modules in Easit GO and get back its name and id.

1
2
3
4
5
6
    {
        modules {
            id,
            name
        }
    }

1
2
3
    {
        "query":"{modules{id,name}}"
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    PS C:\Users\myUser> $apikey = 'myApiKey'
    PS C:\Users\myUser> $url = 'https://urltoEasitGO/graphql/'
    PS C:\Users\myUser> $body = '{"query":"{modules{id,name}}"}'
    PS C:\Users\myUser> $params = @{
        # Using variables set in 'Set up PowerShell' guide
        Uri = $settings.Url
        Authentication = $settings.AuthenticationScheme #Bearer
        Method = $settings.Method #POST
        ContentType = $settings.ContentType #'application/json'
        Token = $settings.Apikey #(ConvertTo-SecureString -String $apikey -AsPlainText)
    }
    PS C:\Users\myUser> $response = Invoke-RestMethod @params

In the response pane of your query tool you should see a list of modules with their id and name. Note that your list may vary from the list shown below as not all instances of Easit GO have ALL modules active.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
    {
        "data": {
            "modules": [
                {
                    "id": 1002,
                    "name": "Contact"
                },
                {
                    "id": 2,
                    "name": "Message"
                },
                {
                    "id": 1001,
                    "name": "Organization"
                },
                {
                    "id": 1012,
                    "name": "Project"
                },
                {
                    "id": 1003,
                    "name": "Request"
                },
                {
                    "id": 1100,
                    "name": "TimeAndExpenses"
                },
                {
                    "id": 1,
                    "name": "User"
                }
            ]
        }
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    PS C:\Users\myUser> foreach ($module in $response.data.modules) {$module}

      id name
      -- ----
    1002 Contact
       2 Message
    1001 Organization
    1012 Project
    1007 Sales
    1100 TimeAndExpenses
       1 User

From the response above we now know the id for each module.

Working with items

We would like to get some requests from Easit GO. Let us take a look at what query operation could fit our need.

Yes, the query operation items ("Fetch items in the specified module") should do the trick. Taking a closer look at the arguments that items accepts, module and limit seems to be good arguments to use. Each query operation have a specific return type, the query operation items will return an item, let us take a look at what fields, or properties, the return type item have. PRO tip, sequenceId is the Easit GO id and id is the GraphQL id for the Easit GO object.

So, let us query the API for requests and as we are a good citizen, we will limit the query to return 100 items. We want to know the GraphQL id (id), Easit GO id (sequenceId) and the item type for the items.

1
2
3
4
5
6
7
    {
        items(module:1003, limit:100){
            sequenceId
            id
            itemType
        }
    }

1
2
3
    {
        "query":"{items(module:1003, limit:100){sequenceId,id,itemType}}"
    }

1
2
3
4
5
    PS C:\Users\myUser> $body = '{
        "query":"{items(module:1003, limit:100){sequenceId,id,itemType}}"
    }'
    # $settings have been created in the setup guide for PowerShell
    PS C:\Users\myUser> $response = Invoke-RestMethod @settings -Body $body

We then get something like this back (we have reduced the number of items to 3 in the example).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
    {
        "data": {
            "items": [
                {
                    "sequenceId": 1,
                    "id": 5,
                    "itemType": 25
                },
                {
                    "sequenceId": 3,
                    "id": 6,
                    "itemType": 19
                },
                {
                    "sequenceId": 7,
                    "id": 8,
                    "itemType": 25
                }
            ]
        }
    }

1
2
3
4
5
6
7
    PS C:\Users\myUser> foreach ($item in $response.data.items) {$item}

    sequenceId id itemType
    ---------- -- --------
            1  5       25
            3  6       19
            7  8       25

Item type 25 and 19, what does that mean? Well, perhaps there is a query operation to find more information about the item types? Gosh darn it, there is! In fact, we have two operations to use. The query operation itemType and itemTypes. Both operations have the return type ItemType and that type have a field called name.

We start with the operation itemType and see what we get. It accepts an id as an argument, let's run a query for itemType 19 and 25.

1
2
3
4
5
    {
        itemType(id:19){
            name
        }
    }

1
    {"query":"{itemType(id:19){name}}"}

1
2
3
4
5
    PS C:\Users\myUser> $body = '{
        "query":"{itemType(id:19){name}}"
    }'
    # $settings have been created in the setup guide for PowerShell
    PS C:\Users\myUser> $response = Invoke-RestMethod @settings -Body $body

We do the exact same thing as above again but change the id to 25 and get the response below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    {
        "data": {
            "itemType": {
                "name": {
                    "nb_NO": "Tjenesteforespørsel",
                    "sv_SE": "Tjänstebegäran",
                    "en_US": "Service Request"
                }
            }
        }
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    {
        "data": {
            "itemType": {
                "name": {
                    "nb_NO": "Sak",
                    "sv_SE": "Ärende",
                    "en_US": "Request"
                }
            }
        }
    }

1
2
3
4
5
    PS C:\Users\myUser> $response.data.itemType.name

    nb_NO               sv_SE          en_US
    -----               -----          -----
    Tjenesteforespørsel Tjänstebegäran Service Request

1
2
3
4
5
    PS C:\Users\myUser> $response.data.itemType.name

    nb_NO sv_SE  en_US
    ----- -----  -----
    Sak   Ärende Request

So, now we now that item type 19 is a Service Request and that 25 is a Request. As a last exercise we will query for all objects in the request module that is of item type Request, and we would like to know when they were created and by who.

1
2
3
4
5
6
7
8
    {
        items(module:1003, itemType:25) {
            sequenceId,
            id
            created
            createdBy
        }
    }

1
2
3
4
5
    PS C:\Users\myUser> $body = '{
        "query":"{items(module:1003, itemType:25) {sequenceId,id,created,createdBy}}"
    }'
    # $settings have been created in the setup guide for PowerShell
    PS C:\Users\myUser> $response = Invoke-RestMethod @settings -Body $body

I will leave it to you to find out who created the requests.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    {
        "data": {
            "items": [
                {
                    "sequenceId": 1,
                    "id": 5,
                    "created": "2023-10-02T07:06:30.801Z",
                    "createdBy": 1
                },
                {
                    "sequenceId": 7,
                    "id": 8,
                    "created": "2023-10-12T13:25:17.314Z",
                    "createdBy": 2
                }
            ]
        }
    }

1
2
3
4
5
6
    PS C:\Users\myUser> $response.data.items

    sequenceId id created             createdBy
    ---------- -- -------             ---------
            1  5 2023-10-02 07:06:30         1
            7  8 2023-10-12 13:25:17         2

Hope you found this guide helpful, please let us know if and how we can improve all our documentation here on techspace by sending an email to support@easit.com.