The API Queries section

This topic describes the API Queries section of the Data model and its options.

In this section, you can create custom API queries that allow you to expose Board data. This data can be retrieved by making REST API calls from any third-party software or service capable of making http/https requests.

When called, queries created in this section will return a dataset in JSON format. You can also configure a Layout query to define the data that will be returned from the API call.

Board APIs have been created specifically for integrating data between Board and external systems, with a machine-to-machine approach in mind.

Before you begin

• The documentation below assumes you have basic familiarity with APIs and Board terminology

• You should have a Client API user created in the Subscription Hub with the necessary authorization to access to the appropriate Board Platform and Data model

• Since Board's APIs are public, the steps to use Board APIs are essentially the following:

  • Obtain an authentication token

  • Call an existing API Query using the custom endpoint generated in the API query configuration panel

To access the API Queries section, access the designer space of the desired Data model and click on the API Queries tile. You will be taken to the API Queries homepage, which displays a table that contains all existing queries in the Data model. The table is sortable and searchable using the interactive header fields.

The table contains the following information for each query:

• Name. This column displays the API query name

• Status. This column displays the status of the API query: either Ready or Draft (if not connected yet)

• Enabled. This column displays a radio button that indicates whether the API is enabled (filled blue) or disabled (unfilled)

• Description. This column displays the descriptions written about the query in its settings

• Has configured layout. This column indicates whether the corresponding API query has a Layout that defines the data it will return.

Creating a new API query

To create a custom API request, proceed as follows:

1. From the API Queries section of the target Data model, click on the orange plus icon  in the top left corner next to "API Queries"

2. In the query configuration panel, give your API a name that will be used to make the API call and write an optional description to explain which data will be returned from the API call.
   Once you enter a name, the custom endpoint will appear at the bottom of the panel. Click the copy icon next to the endpoint to copy its URL in the clipboard
    

3. (Optional) Configure a Layout to define the data that will be returned from the API call. Do not configure a Layout if you want to query the entire Data model

4. Click "SAVE" to save the new query.

Other actions

You can delete or edit one or more existing API queries by selecting them and clicking on the trash icon that appears above the table.

The most up-to-date technical documentation about all Board's public APIs is available by clicking the GO TO DOCUMENTATION button.

Using API queries

Obtaining an authentication token

Before using any API query, you must create a Client API user in the Subscription Hub.

Once you've created the necessary Client API user, an authorization token must be generated before making any request.

The token returned from this request must be used to manage the authentication in the API requests.

The authentication must comply with OAuth2 client credentials flow specifications.

To obtain the authorization token, you need to set the following additional parameters:

• Grant Type: "Client Credentials"

• Access Token URL: https://your-subscription-hub-url/connect/token

• Scope: "public-api"

• Client Authentication: "Send client credentials in body"

Client API users don't consume any Board license, but Roles applied in the "Platform authorization" table in the Client API user panel are always respected.

API queries description

These calls return the result of the specified query on the specified Data model in the form of a JSON document. It is possible to add query string parameters for the Select.

Submission method: GET

/public/{dbName}/query/{queryName}

Parameters

The queryName parameter value must match an existing API query name in the specified Data model. Query parameters are case sensitive.

Response example

{

    "columns": [

        "City",

        "Gross Sales",

        "Sales Packs"

    ],

    "data": [

        [

            "AUSTIN",

            381494.232467651,

            50388.0

        ],

        [

            "BARCELLONA",

            249302.256225586,

            32928.0

        ]

    ]

}

Select querystrings examples

Base

?{entity_name}={member_code}

?year=2012

Result: returns all values from 2012

Multiple

?{entity_name}={member_code}&{entity_name}={member_code}

?year=2012&city=IT01 

Result: returns all values from 2012 and city with code IT01

List

?{entity_name}={member_code},{member_code},{member_code}

?year=2012,2017,2019

Result: returns all values from years 2012, 2017 and 2019

Range

?{entity_name}={member_code}..{member_code}

?year=2015..2019 

Result: returns all values from years 2015 to 2019

Escape

?{entity_name}="{member_code}"

?city="IT01" 

Result: returns all values from city code IT01

json parameter

?json=full 

Result: repeats all keys for each returned record, instead of listing all keys once at the beginning of the returned dataset

Response example:

{

    "data": [

        {

            "city": "AUSTIN",

            "gross Sales": 381494.232467651,

            "sales Packs": 50388.0

        },

        {

            "city": "BARCELLONA",

            "gross Sales": 249302.256225586,

            "sales Packs": 32928.0

        }

    ]

}

By default, the following quotas apply to ApiQuery calls:

• 500 requests per day (this limit can be increased with an additional license. If you need an increase to your quota, please contact your Board Customer Success Manager or Key Account Manager)

• 10 requests per second Board has a timeout of 100 seconds. If the remote API server does not return a response within 100 seconds, Board closes the connection.