Table of Contents

API Requests

On Key API calls accept JSON request bodies. Most GET API calls allow you to specify one or more optional query parameters on the request URI.

Headers

The most commonly used HTTP headers for requests are:

Name Description Example
Accept Specifies the acceptable request formats. Only application/json is supported. Accept: application/json
Authorization Required to get an access token or make API calls. To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme Authorization: Bearer <Access-Token>
Content-Type Specifies the request format. Required for operations with a request body. Content-Type: application/vnd.onkey.entity+json

Content Types

The most commonly used content types for requests are:

Name Description Docs
application/vnd.onkey.entity+json Create a resource or execute a custom resource action using a POST request Link
application/vnd.onkey.entitypatch+json Update a resource or execute a custom resource action using a PATCH request Link
application/vnd.onkey.entitydelete+json Delete a resource using a DELETE request Link

Query Parameters

Note

For all GET requests On Key Query Language parameters can also be added to limit, filter, page, sort, join and parameterize the response data.

The most commonly used HTTP uri parameters used for requests are:

Area Name Description Example
Localisation ct Content translate. Flag to indicate whether phrase translations should be executed on the response content data. ?ct=true
Localisation langId On Key Language id to use for translating the response data. ?langId=1001
Localisation lang On Key Language code to use for translating the response data. ?lang=en

Asynchronous Requests

By default, all On Key API requests are executed synchronously which implies that consumers block until the request has been processed. Most POST,PUT,PATCH and DELETE requests can however also be executed asynchronously.

Note

Asynchronous API requests are not supported for any GET requests

Query Parameters

The HTTP uri parameters used by asynchronous requests are:

Name Description Example
async Flag to enqueue the request for asynchronous execution using a Background Task ?async=true
description Description to use for the asynchronous Background Task ?description=user_rights_calculation
priority Numeric value to prioritise the execution of the asynchronous request ?priority=150

By appending the ?async=true query string parameter, instead of synchronously blocking until the request completes, On Key will register the request as a Background Task and return a unique request identifier. This request identifier supports a Request-Acknowledge-Poll pattern whereby the consumer can poll On Key for progress updates on the background execution or alternatively cancel the asynchronous operation represented by the request identifier.

When submitting an asynchronous API request, On Key will respond with a 202 Accepted status code and include the request identifier using the OnKey-Request-Id header. It will also provide the polling uri to use for checking the background execution status of the request using the OnKey-Request-Location header.

HTTP/1.1 202 Accepted
OnKey-Request-Id: 1584247614480001
OnKey-Request-Location: api/tenants/{client}/{connection}/BackgroundTasks/1584247614480001

When executing the polling uri, the response will contain information such as the status, completedOn and other progress related information for the request execution:

{
    "class": "BackgroundTask",
    "id": 1584247614480001,
    "version": 1,
    "properties": {
        "createdByUserId": 500000000000,
        "createdByUserFullName": "Administrator",
        "createdOn": "2020-03-15T04:46:54.5011350Z",
        "modifiedByUserId": 500000000000,
        "modifiedByUserFullName": "Administrator",
        "modifiedOn": "2020-03-15T04:46:58.7517900Z",
        "completedOn": "2020-03-15T04:46:58.7517900Z",
        "completedSteps": 1,
        "correlationId": "0HLU8JFARMTAT:00000002",
        "failedSteps": 0,
        "instrumentationId": null,
        "name": "user_rights_calculation",
        "origin": "User",
        "startedOn": "2020-03-15T04:46:55.6631980Z",
        "status": "Completed",
        "totalSteps": 1
    }
}

Some of the values included with the response are:

Status Description
status Status of the background task:
  • NotStarted - not started yet
  • Running - currently running
  • Completed - completed
  • Cancelling - being cancelled by user
  • Cancelled - cancelled by user
  • Aborting - being aborted by system
  • Aborted - aborted by system
startedOn start date
completedOn complete date
totalSteps total number of steps to execute
completedSteps number of steps that have completed
failedSteps number of steps that have failed

Using the above-mentioned information, an API consumer can effectively determine the outcome of the asynchronous request submitted.

Request Priority

To prioritize the order in which On Key executes asynchronous requests, append a priority=<numeric value> query string parameter (i.e.?async=true&priority=150) to the request uri.

Note

Scheduled requests can not be prioritised and a priority specified will be ignored.

The following numeric priority ranges are supported:

Range Values Note
Urgent 1-9 Reserved for system usage
High 10-99 High importance user requests
Medium 100-999 Medium importance user requests
Low >= 1000 Low importance user requests

If not specified, On Key enqueues asynchronous API requests using a priority value of 100. As On Key executes asynchronous requests by sorting on the priority and created_on date for the request, an API consumer can change the order in which On Key will attempt to execute a new request by assigning a priority that is less than the priority of any of the pending/executing asynchronous requests.

Warning

Please note that request priorities should not and can not be used as a mechanism to provide order guarantees between executing different requests. It is simply a mechanism to ensure that certain requests can be prioritised and executed before others.

Scheduled Requests

Asynchronous API requests can also be scheduled for execution at a date in the future using a cron expression. Most asynchronous API requests can however only be scheduled for a single date, i.e. recurring schedules are only allowed for a small subset of API requests.

Note

Seconds are not supported within cron expressions.

On Key validates all schedules based on the capabilities for a specific API request and will prevent API consumers from creating an invalid schedule for the request. To identify if a specific API request supports a recurring or single execution schedule, inspect the uriFeatures section of the metadata published by the documentation endpoint for the API request.

Query Parameters

The HTTP uri parameters used by scheduled requests are:

Name Description Example
schedule Cron expression to schedule the asynchronous execution of a request using a Scheduled Background Task. ?schedule=0 22 * * 5 will create a schedule with entries that trigger at 22:00 every Friday evening
from Date and time at which the schedule for the asynchronous execution of the Scheduled Background Task must start. If no value is provided the current UTC is

Example

Consider the following documentation request for the CreateAssetImportance operation on the AssetImportance resource.

curl -v -X GET https://{server}/api/tenants/{client}/{connection}/docs/modules/risk/resources/assetimportance/action/createassetimportance \
-H 'Authorization: Bearer {accessToken}'

The request returns all the metadata for the operation which includes the uriFeatures section shown below:

{
  "type": "Create",
  "name": "CreateAssetImportance",
  "endpoint": {
    "doc": "api/tenants/{client}/{connection}/Docs/Modules/RISK/Resources/AssetImportance/Actions/CreateAssetImportance",
    "href": "api/tenants/{client}/{connection}/Modules/RISK/AssetImportances/",
    "method": "POST",
    "module": "RISK",
    "resource": "AssetImportance",
    "resourceAction": "CreateAssetImportance",
    "type": "primaryAction"
  },
  "uriFeatures": {
    "canSubSelect": false,
    "canRunAsync": true,
    "canSchedule": true,
    "canScheduleRecurring": false,
    "canFilter": false,
    "canOrder": false,
    "canPage": false
  }
  ...
}

The features included within the uriFeatures section are:

Feature Description
canSubSelect can use OKQL $select expression
canFilter can use OKQL $filter expression
canOrder can use OKQL $orderby expression
canPage can use OKQL $top and $skip expressions
canRunAsync can execute asynchronously
canSchedule can be scheduled to execute asynchronously at a single future date
canScheduleRecurring can be scheduled to execute asynchronously at recurring future dates

Scheduling

To schedule an asynchronous API request, append a schedule=<cron expression> query string parameter (i.e.?async=true&schedule=0 22 31 5 *) to the request uri. To configure when a recurring schedule for a request should start, include an additional from=<ISO 8601 date/time> query string parameter (i.e. from=2020-03-31T12:00:00Z). If no from value is provided, On Key will start the recurring schedule for the request using the current UTC. To schedule the once-off execution of an api request on a specific date, omit the schedule cron expression and only specify the date/time at which to execute the request using the from query string parameter.

To further illustrate the scheduling parameters, consider the following examples:

Today schedule from Scheduling behaviour
17/05/2021 0 22 31 5 * 2021-06-01T12:00:00 Schedule the request to fire once a year at 22:00 on 31 May. Only start scheduling on 1 June 2021 which implies that the first occurence will only be on 31 May 2022
17/05/2021 0 22 31 5 * not set Schedule the request to fire once a year at 22:00 on 31 May. Start scheduling using the current UTC so given that today is 17/05/2021, the first occurence will be on 31 May 2021
17/05/2021 not set 2021-06-01T12:00:00 Schedule the request to fire once-off on 1 June 2021 at 12:00
Note

By default On Key predicts job schedules once a day, 7 days in advance, i.e for the next 7 days.

When executing a scheduled asynchronous request, instead of firing off the request, On Key will create a Scheduled Background Task and use the cron expression to create Scheduled Job entries representing the job schedule for the execution of the Scheduled Background Task.

«user»ScheduledBackgroundTask«system»JobScheduledJobBackgroundTaskBackgroundTaskStepexecuted byscheduled asscheduled assteps1..m

Once created, On Key will respond with a 202 Accepted status code and include both the Scheduled Background Task and unique job identifier using the OnKey-Resource-Id and OnKey-Job-Id custom HTTP headers. The OnKey-Job-Schedule-Location uri header can be used to query the list of Scheduled Job request executions whilst the OnKey-Resource-Location header uri can be used to query the Scheduled Background Task created.

HTTP/1.1 202 Accepted
OnKey-Job-Id: cc4820be-e990-4161-85ff-eec4bbde2acb
OnKey-Job-Schedule-Location: api/tenants/{client}/{connection}/Modules/System/Jobs/cc4820be-e990-4161-85ff-eec4bbde2acb/Schedule
OnKey-Resource-Id: 1585760985950002
OnKey-Resource-Location: api/tenants/{client}/{connection}/Modules/System/ScheduledBackgroundTasks/1585760985950002

When executing the OnKey-Job-Schedule-Location uri, the response will contain information such as the status, scheduledOn, startOn and other job related information for the scheduled job execution:

{
    "class": "DomainDynamicRecord",
    "id": 1585743203256507,
    "properties": {
        "name": "DM.DocumentRecord.Create",
        "origin": "BackgroundTask",
        "status": "Scheduled",
        "scheduledOn": "2020-04-01T12:13:22.9016940Z",
        "dispatchedOn": null,
        "schedule": "0,5,10,15,20,25,30,35,40,45,50,55 * * * *",
        "startOn": "2020-04-01T12:45:00.0000000Z",
        "executionMode": "AllOrNone",
        "requestType": "Pragma.OnKey.DM.DocumentRecords.CreateDocumentRecordRequest",
        "response": null,
        "backgroundTaskId": null,
        "backgroundTaskName": null,
        "backgroundTaskStatus": null,
        "backgroundTaskStartedOn": null,
        "backgroundTaskCompletedOn": null,
        "backgroundTaskTotalSteps": null,
        "backgroundTaskCompletedSteps": null,
        "backgroundTaskFailedSteps": null
    }
}

Some of the values included with the response are:

Status Description
status Status of the Scheduled Job:
  • Scheduled - scheduled for execution
  • Dispatched - dispatched for execution
  • Skipped - skipped execution
  • Faulted - could not be dispatched for execution
startOn date and time to dispatch on
scheduledOn date and time scheduled
dispatchedOn date and time dispatched
schedule cron expression used to create the schedule
response error if the Scheduled Job could not be dispatched

Scheduled Execution

On Key actively monitors all the job schedules and enqueues newly triggered Scheduled Job entries as Background Task instances as per the normal asynchronous execution flows.

Note

By default On Key dispatches newly triggered jobs every 60 seconds.

Once On Key dispatches the request using a Background Task, the link between the Scheduled Job and its associated Background Task will allow the API consumer to determine the outcome of the scheduled asynchronous request submitted. When executing the OnKey-Job-Schedule-Location uri again, the job schedule will now contain additional Background Task information:

{
    "class": "DomainDynamicRecord",
    "id": 1585743203256506,
    "properties": {
        "name": "DM.DocumentRecord.Create",
        "origin": "BackgroundTask",
        "status": "Dispatched",
        "scheduledOn": "2020-04-01T12:13:22.9016940Z",
        "dispatchedOn": "2020-04-01T12:40:02.9092360Z",
        "schedule": "0,5,10,15,20,25,30,35,40,45,50,55 * * * *",
        "startOn": "2020-04-01T12:40:00.0000000Z",
        "executionMode": "AllOrNone",
        "requestType": "Pragma.OnKey.DM.DocumentRecords.CreateDocumentRecordRequest",
        "response": null,
        "backgroundTaskId": 1585744802928007,
        "backgroundTaskName": "DM.DocumentRecord.Create",
        "backgroundTaskStatus": "Succeeded",
        "backgroundTaskStartedOn": "2020-04-01T12:40:03.1026270Z",
        "backgroundTaskCompletedOn": "2020-04-01T12:40:07.9210740Z",
        "backgroundTaskTotalSteps": 1,
        "backgroundTaskCompletedSteps": 1,
        "backgroundTaskFailedSteps": 0
    }
}

Using the above-mentioned information, an API consumer can effectively determine the outcome of any scheduled asynchronous request.