New REST APIs

Board 2022 spring release introduces a brand-new set of REST API calls that we designed specifically with a human-to-machine approach: through these new API calls you will be able to connect Board to any third-party software or solution capable of reading data in JSON format and directly query Board at will.

The existing set of APIs, on the ther hand, was created specifically for integrating data between Board and external systems, with a machine-to-machine approach in mind.

Along with the new API calls, we have also introduced a new authentication flow for obtaining the authorization token that 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 OAuth 2.0 Authorization Code with PKCE flow specifications: this new flow has also been extended to the previous set of APIs along with the previous OAuth2 client credentials flow which remains officially supported.

 

The new API calls return various data from Presentations stored in Board. More in particular, they can return:

  • A list of Presentation available to the user
  • Metadata about a specific Presentation
  • A list of Slides from a specific Presentation
  • Metadata about a specific Slide
  • A list of Screen Objects/Layout titles from a specific Slide
  • Data from a single Layout 

 

Configuration

The new API calls follow a standardized syntax, described further below.

Before users can make requests with the new APIs, the following configurations must be set:

  1. Enable the desired API endpoints for the user
  2. Configure a Redirect URI for the OAuth flow. This is the location (a URL or a program) the authorization server will redirect the user back to after successfully authorizing an application
  3. Generate an authorization token. The token returned from this request must be used to manage the authentication in the API calls. The authentication must comply with OAuth 2.0 Authorization Code with PKCE flow specifications

The process is slightly different, depending on whether your Board environment is in the Cloud or on-premises. Read on to know more.

 

Cloud Platforms

To give the user the ability to make API calls using the new authorization flow, the necessary permissions must be granted for each API endpoint.

To grant these permissions to a user, proceed as follows:

  1. Navigate to the "Features" page under the System administration section of your Board Platform
  2. Create a new Application Profile or edit the one applied to the user
  3. Under the "API PUBLIC ACCESS" menu, enable the "Allow presentation public API" option and save changes

 

If you created a new Application Profile for your user, the following additional steps are needed:

  1. Navigate to the "Roles" page under the System administration section of Board
  2. Create a new Role or edit the one assigned to the user
  3. Under the "APPLICATION PROFILE" menu, select the newly created Application Profile from the dropdown and save changes
  4. If you created a new Role, open the user profile panel in the "Users" section of the Board Subscription Hub and assign the new Role to the user

 

Next you need to configure a Redirect URI, that is the URL or program the user will be redirected to after the external application has been authorized through the Oauth flow.

To configure a Redirect URI, proceed as follows:

  1. Navigate to the "General settings" section of the Board Subscription Hub
  2. Click on the "Board API client redirect URIs" menu and enter the necessary redirect URIs. You can add as many fields as you need using the "ADD NEW" button on the right to configure multiple applications at the same time

 

Once you have completed the steps described above, 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 OAuth 2.0 Authorization Code with PKCE flow specifications.

To obtain the authorization token, you need to send the following parameters to a specific Access Token URL: 

  • Grant Type: Authorization Code (With PKCE) 
  • Scope: public-api
  • Client Authentication: Send client credentials in body
  • Client Id: boardpublicapiclient
  • Client secret: 4bb9ed4d-59af-42f6-9c42-250a36a5e1b2
  • auth URL: https://your-subscription-hub-url/connect/authorize
  • Access token URL: https://your-subscription-hub-url/connect/token

Tokens are valid for 1 day from creation and will expire automatically after that time.
If a Client API user is disabled or deleted, any API token created by that user account is deprovisioned at the same time.

 

On-premises installations

To give the user the ability to make API calls using the new authorization flow, the necessary permissions must be granted for each API endpoint.

To grant these permissions to a user, proceed as follows:

  1. Navigate to the "Profiles" page under the System administration section of your Board Platform
  2. Create a new Security Profile or edit the one applied to the user
  3. Under the "API PUBLIC ACCESS" menu, enable the "Allow presentation public API" option and save changes

 

If you created a new Security Profile for your user, the following additional steps are needed:

  1. Navigate to the "Users" page under the System administration section of Board
  2. Select the desired user to open the user details panel
  3. Under the "PROFILE" menu, select the newly created Security Profile from the dropdown and save changes

 

Next you need to configure a Redirect URI, that is the URL or program the user will be redirected to after the external application has been authorized through the Oauth flow.

To configure a Redirect URI, proceed as follows:

  1. Navigate to the "General settings" page under the System administration section of Board
  2. Enter the necessary Redirect URIs in the "Board API client redirect URIs" section of the page, click on the "ADD" button and then click "SAVE" to save it. Repeat the process to add as many Redirect URIs as needed to configure all desired applications

 

Once you have completed the steps described above, an authorization token must be generated before making any request. During the process you will be prompted to enter your Board credentials.

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

The authentication must comply with OAuth 2.0 Authorization Code with PKCE flow specifications.

To obtain the authorization token, you need to send the following parameters to a specific Access Token URL: 

  • Grant Type: Authorization Code (With PKCE) 
  • Scope: public-api
  • Client Authentication: Send client credentials in body
  • Client Id: boardpublicapiclient
  • Client secret: 4bb9ed4d-59af-42f6-9c42-250a36a5e1b2
  • Auth URL: https://your-platform-url/identity/connect/authorize
  • Access Token URL: https://your-platform-url/identity/connect/token

Tokens are valid for 1 day from creation and will expire automatically after that time.
If a Client API user is disabled or deleted, any API token created by that user account is deprovisioned at the same time.

 

 

API calls

Here's an overview of the new "Presentations" set of REST API calls introduced with Board 2022 Spring Release: these calls return various data from the Presentations section of Board (a list of available Presentations, metadata about a specific Presentation, the list of Slides from a specific Presentation, metadata about a specific Slide, a list of Screen Objects/Layout titles from a specific Slide, values from a single Layout).

Unless otherwise indicated below, query parameters are case insensitive.

 

Getting a list of Presentations or a Presentation's metadata

  • Syntax: /public/presentations/{name}
  • Submission method: GET
  • Parameters
    Parameter Value Description Parameter Type Data Type
    name Optional The Presentation name path string
    username Optional The owner of the Presentation query string

  • Example of returned data:
    [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "string",
        "description": "string",
        "creationUTC": 0,
        "lastEditUTC": 0,
        "owner": "string",
        "link": {
          "full": "string",
          "protocol": "string",
          "host": "string",
          "route": "string",
          "parameters": "string"
        }
      }
    ]
  • Notes: Omit the name parameter to obtain the list of available Presentations

 

 

Getting a list of Slides or a Slide's metadata

  • Syntax: /public/presentations/{name}/slides/{slideName}
  • Submission method: GET
  • Parameters
    Parameter Value Description Parameter Type Data Type
    name Required The Presentation name path string
    slideName Optional The Slide name path string
    username Optional The owner of the Presentation query string

  • Example of returned data:
    [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "string",
        "link": {
          "full": "string",
          "protocol": "string",
          "host": "string",
          "route": "string",
          "parameters": "string"
        },
        "type": {
          "slideType": "SectionHeader",
          "message": "string"
        }
      }
    ]
  • Notes: Omit the slideName parameter to obtain the list of available Slides

 

 

Getting a list of all Layout titles/Screen Objects in a specified Slide

  • Syntax: /public/presentations/{name}/slides/{slideName}/toolboxes
  • Submission method: GET
  • Parameters
    Parameter Value Description Parameter Type Data Type
    name Required The Presentation name path string
    slideName Required The Slide name path string
    username Optional The owner of the Presentation query string

  • Example of returned data:
    [
      {
        "name": "string",
        "layoutRow": {}
      }
    ]
  • Notes: If a Layout has no title, the name of the Screen Object will be returned instead (e.g. "DataView"). If multiple Screen Objects of the same type are in the Slide and their Layouts have no title, the call will return the Screen Object followed by a number (e.g. "DataView1", "DataView2", etc.)

 

 

Getting values from a specific Layout/Screen Object in a specified Slide

  • Syntax: /public/presentations/{name}/slides/{slideName}/toolbox/{toolboxName}
  • Submission method: GET
  • Parameters
    Parameter Value Description Parameter Type Data Type
    name Required The Presentation name path string
    slideName Required The Slide name path string
    toolboxName Required The Toolbox name path string
    username Optional The owner of the Presentation query string

  • Example of returned data:
    [
      {
        "name": "string",
        "layoutRow": {}
      }
    ]

 

 

The full up-to-date technical documentation is available right in each active Board Platform. To access it, head to the desired Platform, click on "Data model" from the main menu, select any data model you have in place, and click on "API queries". Once there, click on "GO TO API DOCUMENTATION".

The API DOCUMENTATION in Board