Bulk Requests

In addition to supporting operations that act on a single resource, most resources can also be actioned in bulk. These bulk requests can be used to efficiently action multiple records in a single API request and are especially useful in different data integration scenarios.

The different kinds of bulk requests supported are:

Batch requests
Match Update requests
Import Requests

Content Types

The content types used by bulk requests are:

Name	Description	Docs
`application/vnd.onkey.entitycollection+json`	Create a batch of records for a resource using a `POST` request	Link
`application/vnd.onkey.entitypatchcollection+json`	Update a batch of records for a resource using a `PATCH` request	Link
`application/vnd.onkey.entitydeletecollection+json`	Delete a batch of records for a resource using a `DELETE` request	Link
`application/vnd.onkey.entitymatchupdatecollection+json`	Update properties for a batch of records of a resource to match (i.e. have same values) using a `PATCH` request	Link

Query Parameters

The HTTP uri parameters used by bulk requests are:

Name	Description	Example
`mode`	Mode in which to execute the request: `AllOrNone` - A batch request runs all resources provided in the batch within a single transaction (i.e. the whole batch of resources succeeds or fails together) `PerRecord` - A batch request runs all resources provided in the batch within separate transactions (i.e. individual resources succeed or fail on their own)	`?mode=PerRecord`

Execution Mode

When submitting a bulk API request, the API request can specify an execution mode query parameter to indicate how the request should be executed. A value of ?mode=AllOrNone will run all records in the request within a single transaction and return a single response that contains a success/failure indication that applies to all the records in the request. If any record fails, none of the changes in the request will be applied.

A value of ?mode=PerRecord will run all records in the request within their own transaction and return a single response that contains multiple success/failure indications for every record in the request. Individual records fail or succeed without affecting the outcome of the other records within the same request.

Note

If no mode is specified, On Key defaults to AllOrNone.

Batch Requests

The On Key API supports batch CRUD operations for most resources. A batch CRUD operation can action multiple records in a single API request.

Batch Create

When attempting to create a batch of new records for a resource, a unique identifier (also known as a userObjectId) needs to be specified for every record in the batch. The unique userObjectId allows On Key to associate and echo back any error condition for a specific record in the API response.

To illustrate, consider the following json payload for creating a batch of records for the Asset Importance resource. In this scenario, record2 does not include a description property which violates the business rules for creating a new Asset Importance resource.

curl -v -X POST https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances/batch?mode=PerRecord \
-H 'Content-Type:application/vnd.onkey.entitycollection+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '[{
    "userObjectId" : "record1",
    "properties": {
      "code": "ABC",
      "description": "111111",
      "notes": "notes1",
      "weight": 1
    }
},
{
    "userObjectId" : "record2",
    "properties": {
      "code": "DEF",
      "description": null,
      "notes": "notes2",
      "weight": 2
    }
}]'

When executing this request using ?mode=PerRecord, the response code will be 200 OK with the following response body:

{
    "messages": [
        {
            "code": "Core_Data_RecordCreated",
            "message": "Record successfully created",
            "objectId": "1543841451656001",
            "objectType": "AssetImportance",
            "severity": "information",
            "userObjectId": "record1"
        },
        {
            "code": "Core_LengthValidator",
            "message": "{AssetImportance->Description} must be between 1 and 100 characters. You entered 0 characters",
            "objectType": "AssetImportance",
            "properties": [
                "AssetImportance->Description"
            ],
            "severity": "error",
            "userObjectId": "record2"
        }
    ]
}

Notice that the userObjectId is echoed back for both record1 and record2 to report on whether every record within the batch was successfully created or not. Also note the unique objectId returned for the inserted record1.

The same request executed using ?mode=AllOrNone will result in a response code of 400 Bad Request with the following response body:

{
    "messages": [
        {
            "code": "Core_Resources_SystemRequiredPropertyMissing",
            "message": "{AssetImportance->Description} should not be missing or null",
            "objectType": "AssetImportance",
            "properties": [
                "AssetImportance->Description"
            ],
            "severity": "error",
            "userObjectId": "record2"
        }
    ]
}

Notice that the response now only contains the error for record2 and that record1 was not inserted due to the the execution mode of AllOrNone.

Batch Update and Delete

To update or delete a batch of existing records, the API request needs to specify the id and version for every record in the batch. The id will be used to communicate the success or failure for every record in the batch based on the execution mode selected.

To illustrate, consider the following example for updating a batch of Asset Importance resources.

curl -v -X PATCH https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances/batch?mode=PerRecord \
-H 'Content-Type:application/vnd.onkey.entitycollection+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '[
{
    "id": 1543843155165003,
    "version": 1,
    "operations": [
        {
            "path": "description",
            "value": "changed AA"
        },
    ]
},
{
    "id": 1543843155164002,
    "version": 1,
    "operations": [
        {
            "path": "description",
            "value": "changed BB"
        },
        {
            "path": "notes",
            "value": "some notes update"
        }
    ]
}]'

When executing this valid request using ?mode=PerRecord, the response code will be 200 OK with the following response body:

{
    "messages": [
        {
            "code": "Core_Data_RecordUpdated",
            "message": "Record successfully updated",
            "objectId": "1543843155164002",
            "objectType": "AssetImportance",
            "severity": "information"
        },
        {
            "code": "Core_Data_RecordUpdated",
            "message": "Record successfully updated",
            "objectId": "1543843155164002",
            "severity": "information"
        }
    ]
}

Notice that the objectId is echoed back and contains the unique identity for every record processed in the batch.

An invalid request executed with ?mode=AllOrNone will result in a 400 Bad Request status code with the following response body:

{
    "messages": [
        {
            "code": "Core_LengthValidator",
            "message": "{AssetImportance->Description} must be between 1 and 100 characters. You entered 0 characters",
            "objectId": "1543844764239005",
            "objectType": "AssetImportance",
            "properties": [
                "AssetImportance->Description"
            ],
            "severity": "error"
        }
    ]
}

Notice the objectId in the response body to indicate the record in the batch that failed.

Match Update Requests

The On Key API supports the match update of properties for a resource. A match update will update the same set of properties for a batch of records for the same resource to all have the same value (i.e. they will all match) across the different record instances.

Note

Match update is only supported for a select sub-set of properties (if any) for a resource. Use the Hypermedia associated with a resource to see if match update operation is available.

To illustrate, consider the following example for updating the description property of the Asset Importance resource to have the same value for two different records:

curl -v -X PATCH https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances/matchbatch?mode=PerRecord \
-H 'Content-Type:application/vnd.onkey.entitymatchupdatecollection+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
    "records": [
        {
            "id": 1543843155165003,
            "version": 1
        },
        {
            "id": 1543843155165002,
            "version": 3
        }
    ],
    "operations": [
        {
            "path": "description",
            "value": "Same value for all records"
        }
    ]
}'

As with batch requests, match update requests can be executed using either the AllOrNone or PerRecord execution mode. The same error mechanism used for Batch Update and Delete responses also applies to match update responses.

Table of Contents

Bulk Requests

Content Types

Query Parameters

Execution Mode

Note

Batch Requests

Batch Create

Batch Update and Delete

Match Update Requests

Note