29 January 2024

OData APIs enable data to be retrieved from Data Engine. Full reader OData APIs enable you to query current data. Temporal OData APIs enable you to query historical data from the past three months.

Get started with the OData APIs by obtaining an access token and then using the access token to interact with the OData APIs in Postman.

Before getting started you require the following:

• Username and password of an account that has data access permissions for Data Engine.

• Tenant name for the institution. If you do not know the tenant name, contact Tribal support.

• The identity server URL for the institution, such as https://identity.tribaledge.com/region_name/ids/tenant_name/connect/token, where region_name is the region such as EMEA or APAC, and tenant_name is the tenant name such as hessle. For example, https://identity.tribaledge.com/emea/ids/hessle/connect/token.

• The endpoint URLs to interact with after obtaining an access token. For example, https://api.tribaledge.com/emea/odsservice/hessle/odata/entity. You must replace entity with the name of the entity you want to interact with, such as People or Applications. For example, https://api.tribaledge.com/emea/odsservice/hessle/odata/People or https://api.tribaledge.com/emea/odsservice/hessle/odata/temporal/People. For more information, go to Data Engine message types.

• Postman to obtain the access token from Identity server and then interact with the OData APIs. The latest version of Postman can be downloaded from the website: Postman download.

Then, get started as follows:

1. Obtain an access token from Identity server

2. Interact with the OData APIs in Postman

Obtain an access token from Identity server

Obtain an access token from Identity server as follows:

1. In Postman, create a new POST request for a token. Select New and then select HTTP request.

   Then, select POST from the drop-down list and add the identity server URL in Enter request URL, as shown in the image New POST request.

   For example, https://identity.tribaledge.com/emea/ids/hessle/connect/token.

   

2. Go to the POST request body and select x-www-form-urlencoded. Then, add the key-value pairs as defined in the table POST request body.

   POST request body

   Key	Notes
   grant_type	Type of authorisation used to request a token. This must be set to password.
   username	Username of the account, such as hessle.tde.
   password	Password of the account, such as //++\7T$tw3gQL,u.
   audience	Authentication audience, this must be set to all_resources.
   client_id	Client identification, this must be set to apiclient.
   client_secret	Client secret, this must be set to apisecret.

   The image POST request for token shows the POST request body with the key-value pairs highlighted.

   

3. Send the POST and wait for a response.

   If successful, the API returns a 200 OK status and an access token as shown in the image Access token obtained.

   If the request is unsuccessful, the API returns a 400 Bad Request status and a message indicating the specific error. For example, The resolved tenant is invalid indicates that the POST URL is incorrect.

   

Interact with the OData APIs in Postman

Use the access token to interact with the OData APIs in Postman as follows:

1. In Postman, copy the access token from the response pane.

   You must copy the access token without the quotation marks as these are not part of the access token.

2. In Postman, create a new GET request to retrieve the application. Select New and then select HTTP request.

   Then, select GET from the drop-down list and add the endpoint URL in Enter request URL. For example, retrieve the current or historical data for the People entity as follows:

   Full reader OData endpoint URL for current data

   https://api.tribaledge.com/emea/odsservice/hessle/odata/People

   Temporal OData endpoint URL for historical data

   https://api.tribaledge.com/emea/odsservice/hessle/odata/temporal/People?PeriodFrom=2023-03-01T10:00:00&PeriodTo=2023-04-01T17:00:00.

   The PeriodFrom and PeriodTo parameters are mandatory and must be in the format, YYYY-MM-DDTHH:mm:ss. Also, PeriodFrom date cannot be more than three months in the past.

3. Go to the GET request Authorisation and select Bearer token. Then, paste the bearer token from step 1.

4. Send the GET and wait for a response.

   If the request is successful, Postman displays a 200 OK status, as shown in the image Successful API request.

   If the request is unsuccessful, the API returns a status and a message indicating the specific error. For example, 401 Unauthorised which indicates that authorization was not successful.