The API in general uses HAL as message format which provides a standardized and easy-to-use way to represent a resource and links to other resources. A link usually return you exactly one resource, for example one entry of a taxonomy. And you have links accepting URL template parameters that return you one resouce. That’s clean and follows the principles of RESTful interfaces.
However, it means that you need a huge amount of HTTP requests if you want to get the resources for tens, hundreds or even thousands of resources. This is an issue in itself, especially when client and service are a long way apart, e.g. on different continents. Even more important is the fact, that a service can’t use an optimized implementation for a list of resources, like using optimized SQL statements or bulk calls to other backend services, because each resource is requested invidually.
That’s why Avid introduced bulk calls in CTMS. They deviate slightly from the usual HAL patterns, but bring an enormous performance benefit in some use cases.
To simplify implementation and usage of bulk requests, all bulk requests follow the same pattern with the same general request and response format. Of course the details of the returned elements differs depeneding on the kind of request.
Naming Scheme
Bulk link rels have the same name as a corresponding non-bulk link rels, but with a suffix of "-bulk".
Example: There is a bulk link rel taxonomies:entry-by-entryid-bulk that can be used to query the information for an array of taxonomy entries. For each element, the call returns the same JSON as the regular link rel taxonomies:entry-by-entryid would return.
For bulk versions of long-running commands, the order of suffixes is always "-bulk-command".
Request
All bulk requests have a number of things in common:
HTTP method
Bulk requests need a body, which is not supported for GET and DELETE requests. That’s why the HTTP method of bulk requests depends on the HTTP method of the corresponding non-bulk call:
-
If the non-bulk call uses POST, PUT, or PATCH, the bulk call will use the same HTTP method.
-
If the non-bulk call uses GET or DELETE, the bulk call will use POST as method.
Query parameters
The request will usually accept the same query parameters as the non-bulk call unless stated otherwise in the description of the bulk request. The query parameters are applied to all items in the request.
Body
The body depends on the details of the non-bulk version of the call:
Single query or URL path parameter
If the non-bulk call doesn’t accept a body, but one query parameter then the bulk call expects an array as body:
[
"id1",
"id2"
]HAL resource as body
If the non-bulk version of the link rel expects a HAL resource as body (example: taxonomies:create-or-update-entry-bulk), then the bulk call expects an array of HAL resources as body:
[
{ HAL resource 1 },
{ HAL resource 2 }
]Multiple query or URL path parameters
If the non-bulk call has multiple query or path parameters (example: a future taxonomies:entry-by-taxonomyid-and-entryid-bulk link rel as a bulk version of taxonomies:entry-by-taxonomyid-and-entryid) then the body will be an array of JSON objects. Each JSON object contains properties with the names of the query parameters:
[
{
"taxonomyid": "ABC",
"entryid": "123"
},
{
"taxonomyid": "XYZ",
"entryid": "458"
}
]Response
HTTP status
The HTTP response code for the entire call is usually 200 OK, unless the call fails completely.
If it fails for only some elements (e.g. if you query five assets and one doesn’t exist), then the response will still be 200 OK and the body will contain detailed information about the result for each requested entity.
Body
The response body consists of a JSON array, where each array item corresponds to an item in the request.
Example
Example for the response of a bulk call that requested information about three items
[
{
"success": true,
"data": { … },
"headers": {
"Last-Modified": "Wed, 21 Oct 2015 07:28:00 GMT"
}
},
{
"success": false,
"httpStatus": 404,
"errorCode": "avid.mam.assets.access/NOT_FOUND",
"errorMessage": "unknown object 2019011614271751270000000010000000000000000015716B00000D0D000002",
"errorParams": {
"id": "2019011614271751270000000010000000000000000015716B00000D0D000002"
}
},
{
"success": true,
"data": { … }
}
]
This response means:
-
The first requested item is returned successfully. The HAL resource for the item itself is in the data property.
-
The second requested item was not found. httpStatus is 404 for "NOT FOUND". errorCode, errorMessage and errorParams contain details about the error.
-
The third requested item is returned successfully. The HAL resource for the item itself is in the data property.
Properties in the response body
Each item in the array has the the following properties:
Property |
Type |
Description |
|---|---|---|
success |
boolean, mandatory |
true, if the call succeeded for the item, false if not. |
headers |
map of string to string, optional |
special HTTP headers that the non-bulk call would return. |
If the call was successful for this item (success is true): |
||
data |
JSON, optional |
Contains the same JSON structure as the non-bulk call would return for the item in the request. |
httpStatus |
int, optional |
HTTP status code that the non-bulk call would return for the item in the request. |
If the call was not successful for this item (success is false): |
||
httpStatus |
int, optional |
HTTP status code that the non-bulk call would return for the item in the request. |
errorCode |
string, optional |
Machine-readable error code that the non-bulk call would return for this item. |
errorMessage |
string, optional |
Human-readable error message that the non-bulk call would return for this item. |
errorParams |
map of string to string, optional |
New in MC | Cloud UX 2022.12 Error parameters that the non-bulk call would return for this item. |