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 home page, 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
- 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:
- From the API Queries section of the target Data model, click on the +API QUERY button
- 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
- (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
- Click "SAVE CHANGES" to save the new query.
Other actions
You can delete one or more existing API queries by selecting them and clicking on the DELETE button 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 API 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 have 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 querystring parameters for the Select.
Submission method: GET
Syntax: /public/{dbName}/query/{queryName}
Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
| dbName | Required | Database name | path | string |
| queryName | Required | API query name | path | string |
| json | Accepted Value: full (Optional) |
Set the parameter to full to repeat keys for each returned record | query | string |
The queryName parameter value must match an existing API query name in the specified database.
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 with 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. If the remote API server does not return a response within 100 seconds, Board closes the connection.
Learn more: