Call a destination API

This guide explains how to call a destination API.

tip

To maximize the value of this guide, it is recommended to read up on the following concepts:

• Destination

Destination

Created from Occtoo Studio in a few easy steps, each destination has a unique URL comprising the customer identifier, destination identifier, and destination version. Destination versions allow different instances to run simultaneously, enabling changes without breaking existing consumers.

Documentation

All published destinations expose an OpenAPI URL, which can be used to view and try different endpoints. The OpenAPI URL is the destination base URL with the suffix '/openapi'.

https://global.occtoo.com/exampeltenant/exampeldestination/v1/openapi

Unprotected and protected destinations

A destination can be either unprotected or protected. An unprotected destination is public, meaning it is available to anyone with access to the URL and does not require authentication. Protected destinations, on the other hand, restrict access to authorized users only, ensuring that sensitive data and functionalities are secure. Authentication for protected destinations is done using an access token.

Retrieving an access token for protected destinations

Similar to sources, access is managed through the use of applications (comparable to data providers in sources) which are managed on individual destination verisons. Using application information (ID and secret) and the destination ID, a token can be generated.

Register application

Before a token can be generated, an application needs to be registered for the destination. This is done on the specific destination version in Occtoo Studio under the tab Applications. After creation, the secret will be displayed. Make sure to copy it, as it will not be possible to retrieve later. However, it is possible to reset the secret at any point.

Generate an access token

To generate an access token the following is needed:

• Destination ID: found under the settings tab on the destination version
• Client ID: from application listing
• Client secret: from application registration

A access token can be generated by doing a POST request to the URL below, substituting {@DESTINATION-ID} with the ID of the destination.

https://destinations.occtoo.com/destinations/{@DESTINATION-ID}/token

The POST request needs to contain a JSON body carrying the properties clientId and clientSecret. These properties correspond to the identifiers provided by the application used to access the destination.

{
    "clientId" : "{@APPLICATION-ID}",
    "clientSecret": "{@APPLICATION-SECRET}"
}

info

The lifetime of a destination token is 60 minutes. After that a new token needs to be generated.

Below one will find simple code examples generating an access token for a protected destination.

Code samples

cURL

curl --location 'https://destinations.occtoo.com/destinations/{@DESTINATION-ID}/token' \
--header 'Content-Type: application/json' \
--data '{
    "clientId" : "{@APPLICATION-ID}",
    "clientSecret": "{@APPLICATION-SECRET}"
}'

C#

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var baseAddress = "https://destinations.occtoo.com/destinations/";
var destinationClientId = "@APPLICATION-ID";
var destinationSecret = "@APPLICATION-SECRET";
var destinationId = "@DESTINATION-ID";

var httpClient = new HttpClient();
httpClient.BaseAddress = new Uri(baseAddress);

dynamic credentials = new { clientId = destinationClientId, clientSecret = destinationSecret };

var content = new StringContent(JsonConvert.SerializeObject(credentials), Encoding.UTF8, "application/json");

var tokenResponse = await httpClient.PostAsync($"{destinationId}/token", content);
var tokenResponseContent = await tokenResponse.Content.ReadAsStringAsync();
var tokenDocument = System.Text.Json.JsonSerializer.Deserialize<JsonDocument>(tokenResponseContent);
var token = tokenDocument.RootElement.GetProperty("result").GetProperty("accessToken").GetString();

JavaScript

// Example assumes you've patched fetch with node-fetch:
// npm install node-fetch
// globalThis.fetch = await import('node-fetch').then(m => m.default)

(async () => {
  const baseAddress = "https://destinations.occtoo.com/destinations/";
  const destinationClientId = "@APPLICATION-ID";
  const destinationSecret = "@APPLICATION-SECRET";
  const destinationId = "@DESTINATION-ID";

  function getToken() {
    return fetch(baseAddress + destinationId + "/token", {
      method: 'POST',
      headers: {
        Content-Type: 'application/json',
      },
      body: JSON.stringify({
        clientId: destinationClientId,
        clientSecret: destinationSecret
      })
    });
  }

})();

Calling a protected destination

To access a protected destination API, users must use the obtained access token as a bearer token. The bearer token must be included in the authorization header of every API request, formatted as 'Authorization: Bearer {@DESTINATION-ACCESS-TOKEN}'.

curl --location 'https://global.occtoo.com/exampeltenant/exampeldestination/v1/exampelendpoint' \
--header 'Authorization: Bearer {@DESTINATION-ACCESS-TOKEN}'
}'

Response

The structure of the response object remains consistent whether it's a POST or a GET request. It always includes the language being retrieved and an array of result objects. If there are no results, an empty array is returned. The result objects vary between endpoints and destinations, as they are configured individually.

For more details on how to alter the information to include in the response, see the page data consumption.

Tailoring the response to your needs

Occtoo offers users the possibility to modify the API response via advanced filtering and facets. Tailor responses by applying precise filters through query parameters in GET requests or a powerful filter object in POST requests. Utilize inclusion, exclusion, and range conditions to get exactly the data you need. Enhance your data navigation by implementing facets, providing categorized value counts for a seamless user experience.

For more details on filtering and facets, see the page data consumption.

Try it out!

We have prepared a sample destination that can be used to test different queries with. The API does not require any authentication so you are good to go!

https://global.occtoo.com/occtoodemo/googleMarketplace/v3/openapi

tip

To try the feature go to https://editor-next.swagger.io/. From the menu select File and then Import URL and enter the OpenAPI URL to see, and test, the destination. If it is a protected destination, client id and secret need to be provided.