Search for answers or browse our knowledge base

Click here for Partner information on Installing and Upgrading

Login here for full access

API usage

Updated on December 10th, 2022

Table of Contents

X
Oidc Client Access Token Sending a request GET POST Process Engine Curator API API Client configuration

Using the Curator APIs is a simple three-step process:

  1. Set up an oidc-client instance to handle authorization with Curator Gateway
  2. Get an access token from the Curator Gateway
  3. Send Request

Oidc Client

Any and all requests go through Curator Gateway, therefore all API requests require an access token to be routed correctly.

For JavaScript clients, we recommend using an oidc-client in order to authorize a user and be issued an access token. This is the same way a user is currently authorized for all the main Curator applications. At a minimum, the creation of an Oidc.UserManager instance with the following settings would be required. Ideally, it would be created in a constructor when your application starts up.

/**
  * Builds an Oidc client which helps you sign in to CG without passing around secure information
  * see for more details & options https://www.npmjs.com/package/oidc-client
  */
buildAuthoriser() {
    return new Oidc.UserManager({
        userStore: new Oidc.WebStorageStateStore(),
        // Required settings
        authority: gatewayUrl, // The url to gateway
        client_id: clientId, // The guid client id you are representing e.g Cliplink
        redirect_uri: window.location ,
        response_type: 'id_token token',
        scope: 'openid Curator.Gateway.API Curator.Server.API Curator.ProcessEngine.API', //The scope being requested from the OIDC/OAuth2 provider. Could also have ["profile email roles"]        
    });
}

Access Token

Once you have your oidc client, you need to get the access token. It will be in your URL; alternatively, the following code will obtain it then put the URL back to its original state.

Note: this .auth is the oidc-client instance.

/**
* Gets the access token
* @returns {promise} once promise resolves it returns the access token
*/
getAccessToken() {
  // Checks if we have the access token in the url. Gets returned with # in the url, if it is not found it gets it.
  let hasQuery = window.location.href.indexOf('#') !== -1; // If index is -1 no # found
  if (hasQuery) {
      return this.auth.signinRedirectCallback().then(u => {
          var accessToken = "Bearer " + u.access_token; // Need this or Curator Gateway wil not let you in. Proves you are authorised user
          window.history.pushState({}, '', window.location.origin + window.location.search); // This sets the url back to what it was before the CG login window appears i.e. original url
          return accessToken;
      }).catch(err => {
          // Will print any error returned to console
          console.error(err);
      });
  } else {
       // uses the Oidc instance created in the buildAuthoriser function to get access token
       this.auth.signinRedirect().catch(err => {
          // Any errors get caught here and printed to console.
          console.error(err);
      });
  }
}

The authorization header will need to be in the format of Bearer <access token> which the above function will build for you.

Sending a request

GET

The following code snippet is a jquery HTTP request. You can use whatever requester you want as long as you can add headers/include a body if required.

$.ajax({
    url: url,
    headers:{
        Authorization: accessToken,
    },
    contentType: 'application/json',
    data: body,
    type: "GET",
    success: result => {
        // Do something with the request response
    },
    error: function(xhr, status, error){
        // An error occured, should do something as a result
    }
})

The URL will be in the form of {{baseGatewayUrl}}/{{ApiUrl}} for example:

My base gateway URL is: https://curator.com/curatorgateway 

My API URL is: processengine/web/version

When combined, it will look like this: https://curator.com/curatorgateway/processengine/web/version. This request obtains the Process Engine version but is authorized through the Curator Gateway to a specific user.

POST

With sending data all that needs change is the type of the request and to add a body.

/**
* Sets the passed in metadata field to the passed in value for the assetID in the url
*
* @param {string} metadataField, the metadataname field
* @param {string} value, the new value for the metadata field
* @param {string} assetID, the asset id of the asset we are modifying
*/
setAssetMetadata(metadataField, value, assetId){      
  // Using the api urls build our request, This will get all metadata for the relevant asset ID.
  var apiUrl = "/api/v1/assets/" + assetId + "/metadata/" + metadataField; // Sets the set asset metadata api call url. Found in the API Documentation
  var url = gatewayUrl + apiUrl; // Append the api url to the base url so we are asking the right CG instance
  // Build the body  of the request that contains the new value of the metadata field
  var body = "[\""+ value + "\"]";
  $.ajax({
      url: url,
      headers:{
          Authorization: this.accessToken,
      },
      contentType: 'application/json',
      data: body,
      type: "PUT",
      success: result => {
          this.getAssetMetadata();
      },
      error: function(xhr, status, error){
          console.log(xhr);
           $('#error').html("Status: " + status + " Error: " + error);
      }
  })
}

Process Engine

The Starting and monitoring a Process via the Curator API article covers a lot of how to talk to the Process Engine API but the only change is that it should be routed through Curator Gateway just like the above sections i.e.,

{{baseGatewayURL}}/{{processEngineApiUrl}}

Which would look like: https://curator.com/curatorgateway/processengine/web/processdefinition/name in full. This example is the URL to obtain a Process Definition Name; see further API documentation for all the URLs.

Curator API

A full list of the API URL documentation can be viewed from this link. This can also be accessed by navigating to your Curator Gateway instance - from the API tab on the left (see the image below), API calls available in your release and their associated documentation can be seen.

NOTE: you must have the Admin role to view this section.

API Client configuration

Instructions on how to Configure the Client application in the Curator system and use that configuration for the Client can be found in the API Client configuration article.

Was this article helpful?

Related Questions