API Overview

The Digital.ai Platform API is a REST API, which means that you can use standard HTTP methods (GET, POST, PATCH, PUT, and DELETE) to retrieve, submit, change, and delete data. To ensure data privacy, the API is served over HTTPS; unencrypted HTTP is not supported.

REST also uses Uniform Resource Identifiers (URIs) and most often JavaScript Object Notation (JSON) conventions for data exchange between the client and the server.

The REST Interface operates using the configuration datastores defined in NETCONF. REST defines a set of Create, Retrieve, Update, Delete (CRUD) operations that can be used to access these datastores.

How It Works

Each interface provides a set of API resources that let you perform various Platform tasks. Each resource has a URL (or endpoint) on the Digital.ai server. To call a resource, you send a request to the appropriate URL, and the Digital.ai server responds with JSON-formatted data.

When you make a request to the REST API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and a response body.

The REST operations GET, POST, PATCH, PUT, and DELETE are described as follows:

• GET - The GET method is used to retrieve/request data for a resource.
• POST - The POST method is used to create a data resource or invoke an operation resource.
• PATCH - The PATCH method is used to create or update a sub-resource within the target resource. If the target resource instance does not exist, the server will not create it.
• PUT - The PUT method is used to create or replace the target resource.
• DELETE - The DELETE method is used to delete the target resource.

Authentication

Rest API authentication is used to authenticate users and applications when performing API tasks. Authentication is a must to ensure that APIs are secure and accessible only to authorized users.

Digital.ai Platform supports Token Authentication. The token can be obtained via Basic or OAuth mechanisms but the API accepts only bearer tokens.

Service-to-Service Authentication

In order to consume Platform Services outside of a user session, services need to authenticate themselves. When responding to a web request on behalf of a user, a service can simply use the Bearer Token it already possesses. However, in other scenarios, the service may require separate authentication with the Platform. This section provides a detailed explanation of the authentication process for such services.

The service-to-service authentication process utilizes the OAuth 2.0 Client Credentials Grant. To initiate this process, a For API Use application needs to be created that will auto-create a Client within the system. Once the Client is created, the authenticating service can utilize the associated client_id and client_secret to obtain an access token.

Perform the following steps to do this action:

1. Create Client

To create a client, you need to create an application:

1. Log in to Digital.ai Platform.

2. In the left navigation, click Applications.

   Alternatively, you can click the Create application button on the Platform Overview page.

3. In Select application, choose For API Use as the application type.

4. In Instance name, assign the application's custom name.

5. In URL, add the URL that you will be redirecting to after authentication.

6. Click Next to proceed to the Advanced configuration section.

7. Accept the default values on the Advanced configuration and Mappers pages.

8. On the Get client ID & secret page save the Client ID and Client Secret values.

9. Click Complete to finish creating the application and the associated client.

2. Use /token to get a token (as described in the OIDC spec)

To get a token:

1. Determine token URL

   a. Call this endpoint, provide your vanity subdomain in the ?hint= parameter.

   https://api.us.digital.ai/identity/v1/accounts/auth/configuration/?hint=<vanity subdomain here>

   curl -X GET "https://api.digital.ai/identity/v1/accounts/auth/configuration/?hint=champagne" -H "accept: application/json"

   b. In the response, retrieve the token_endpoint value, for example:

   https://identity.us.digital.ai/auth/realms/champagne/protocol/openid-connect/token

2. Prepare POST request with the following details:

   a. Headers:

   • content-type = application/x-www-form-urlencoded

   • Default headers usually ok for most HTTP Clients

   b. Body: (x-www-form-urlencoded)

   • grant_type = client_credentials

   • client_id = insert Client ID from "Create Client" section.

   • client_secret = insert Client Secret from "Create Client" section.

   • scope = openid dai-svc

   c. Retrieve access_token from token endpoint response.

Example request

curl --location --request POST \
'https://identity.us.digital.ai/auth/realms/champagne/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<client id retrieved from create client section>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret=<client secret retrieved from create client section>' \
--data-urlencode 'scope=openid dai-svc' 

Example response

{
   "access_token": "SlAV32hkKG",
   "token_type": "Bearer",
   ............
}

3. Use the token to access the Digital.ai API Reference

To access the API Reference:

1. Determine the API you want to hit.

2. Add the access_token as a Bearer token in the Header by adding the following Header:

   a. Authorization = Bearer (insert access token)

Example request

curl --location --request GET 'https://api.us.digital.ai/licensing/products' \
--header 'Authorization: Bearer <access_token>'

Digital.ai Platform API Reference

The Digital.ai Platform API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation.

For more information, see API Reference.