Inserting data in batch

For cloud customers on Azure, it is possible to insert and update data in bulk with the REST API. A specific BATCH endpoint is available to support these requests.

BATCH operations

With the batch operation, it is possible for API clients to perform multiple actions, like inserts and updates, for multiple resources within a single request.

Batch size

Batch API use is subject to the standard API usage limits. Each HTTP request counts as one call when calculating usage limits. Next to that, a batch can contain a maximum of 100 records per request.

Headers

The main request headers are applied for all the requests from the batch action. It is not possible to set the headers for each individual request.

Request body

A JSON batch request body consists of a single JSON object that MUST contain the name/value pair requests.

The value of requests is an array of request objects, each representing an individual request. All requests which have no atomicity group set will be processed in separate transactions. Note: an individual request MUST NOT itself be a batch request.

A request object MUST contain the name/value pairs id, method, and url, and it MAY contain the name/value pairs atomicityGroup, dependsOn, and body. The table below explains more about these name/value pairs.

Name/Value	Required	Explanation
id	✅	The value of this property is a string containing the request identifier of the individual request. It allows only alphanumerical, dashes, dot, and underscore characters. It MUST NOT be identical to the value of any other request identifier nor any atomicityGroup within the batch request.
method	✅	The value of this property is a string that MUST contain one of the literals DELETE, PATCH, POST, or PUT. These literals are case-insensitive.
url	✅	The value of this property is a string containing the individual request URL. The URL MUST be an absolute path which is appended to scheme, host, and port of the batch request URL. It should not start with a slash. Note: only Object is supported, it is not possible to execute multiple REST workflows in batch.
body	❌	The value of this property can be null, which is equivalent to not specifying the body name/value pair. More information about the request body of a single request can be found here.
atomicityGroup	❌	The value of this property is a string whose content MUST NOT be identical to any value of id within the batch request. It allows only alphanumerical, dashes, dot, and underscore characters. All request objects with the same value for atomicityGroup MUST be adjacent in the requests array. These requests are processed as an atomic operation and in a SINGLE transaction and MUST either all succeed, or all fail. If one of the requests fails, then all the other requests from that atomicity group will have a response with status code 424 - Failed Dependency.
dependsOn	❌	The value of this property is an array of strings whose values MUST be id-values of preceding request objects; forward references are not allowed. dependsOn property can be used only for requests without an atomicity group or for requests with the same atomicity group. It is possible to reference the request which it depends on to get the correct entity and identifier combination. The syntax for this is $[dependsOn_id]. If one of the requests it depends on has failed, the dependent request is not executed and a response with status code of 424 - Failed Dependency is returned for it as part of the batch response.

Example of a BATCH request

POST https://customer.ultimo.net/api/v1/batch

{ 
    "requests": [{ 
            "id": "1", 
            "method": "PUT", 
            "url": "Object/Equipment('00001')", 
            "body": { 
                "Context": 1, 
                "Description": "Asset", 
                "InstallDate": "2022-04-07", 
                "NextPmMaintenanceDate": "2023-04-07", 
                "Status": 2, 
                "CostCenter": "01", 
                "Department": "01" 
            } 
        }, { 
            "id": "2", 
            "method": "POST", 
            "url": "Object/Equipment", 
            "body": { 
                "Context": 1, 
                "Description": "Asset", 
                "InstallDate": "2022-04-07", 
                "NextPmMaintenanceDate": "2023-04-07", 
                "Status": 2, 
                "CostCenter": "01", 
                "Department": "01" 
            } 
        }, { 
            "id": "3", 
            "method": "PATCH", 
            "url": "Object/Equipment('00001')", 
            "body": { 
                "Description": "Installation" 
            } 
        }, { 
            "id": "4", 
            "method": "DELETE", 
            "url": "Object/Equipment('00001')" 
        } 
    ] 
} 

Example of a BATCH response

{ 
    "responses": [{ 
            "id": "1", 
            "status": 201, 
            "body": { 
                "Id": "00001", 
                "Context": 1, 
                "Description": "Asset", 
                "InstallDate": "2022-04-07", 
                "NextPmMaintenanceDate": "2023-04-07", 
                "Status": 2, 
                "CostCenter": "01", 
                "Department": "01" 
            } 
        }, { 
            "id": "2", 
            "status": 201, 
            "body": { 
                "Id": "39939", 
                "Context": 1, 
                "Description": "Asset", 
                "InstallDate": "2022-04-07", 
                "NextPmMaintenanceDate": "2023-04-07", 
                "Status": 2, 
                "CostCenter": "01", 
                "Department": "01" 
            } 
        }, { 
            "id": "3", 
            "status": 200, 
            "body": { 
                "Id": "00001", 
                "Context": 1, 
                "Description": "Installation", 
                "InstallDate": "2022-04-07", 
                "NextPmMaintenanceDate": "2023-04-07", 
                "Status": 2, 
                "CostCenter": "01", 
                "Department": "01" 
            } 
        }, { 
            "id": "4", 
            "status": 204 
        } 
    ] 
} 

Example of a BATCH request with atomicityGroup and dependsOn

POST https://customer.ultimo.net/api/v1/batch

{ 
    "requests": [{ 
            "id": "1", 
            "method": "PUT", 
            "url": "Object/Department('01')", 
            "body": { 
                "Context": 1, 
                "Description": "Department", 
                "Status": 0 
            } 
        }, { 
            "id": "2", 
            "method": "PUT", 
            "dependsOn": ["1"], 
            "url": "Object/Employee('000001')", 
            "body": { 
                "Context": 1, 
                "Description": "John Doe", 
                "Status": 0, 
                "Department": "01" 
            } 
        }, { 
            "id": "a1", 
            "method": "POST", 
            "atomicityGroup": "group1", 
            "url": "Object/Invoice", 
            "body": { 
                "Context": 2, 
                "Status": 1, 
                "Description": "Invoice", 
                "Vendor": "2513", 
                "Site": "23" 
            } 
        }, { 
            "id": "a2", 
            "method": "POST", 
            "atomicityGroup": "group1", 
            "dependsOn": ["a1"], 
            "url": "Object/$a1/Lines", 
            "body": { 
                "Context": 2, 
                "Status": 1, 
                "Description": "Invoice line 1" 
            } 
        }, { 
            "id": "a3", 
            "method": "POST", 
            "atomicityGroup": "group1", 
            "dependsOn": ["a1", "a2"], 
            "url": "Object/$a1/Lines", 
            "body": { 
                "Context": 2, 
                "Status": 1, 
                "Description": "Invoice line 2" 
            } 
        } 
    ] 
}

Example of a BATCH response with atomicityGroup and dependsOn

{ 
    "responses": [{ 
            "id": "1", 
            "status": 200, 
            "body": { 
                "Id": "01", 
                "Context": 1, 
                "Description": "Department", 
                "Status": 0 
            } 
        }, { 
            "id": "2", 
            "status": 200, 
            "body": { 
                "Id": "000001", 
                "Context": 1, 
                "Description": "John Doe", 
                "Status": 0, 
                "Department": "01" 
            } 
        }, { 
            "id": "a1", 
            "status": 201, 
            "body": { 
                "Id": "001", 
                "Context": 2, 
                "Description": "Invoice", 
                "Status": 1, 
                "Site": "23", 
                "Vendor": "2513" 
            } 
        }, { 
            "id": "a2", 
            "status": 201, 
            "body": { 
                "Id": { 
                    "Invoice": "001", 
                    "LineId": "0001" 
                }, 
                "Context": 2, 
                "Description": "Invoice line 1", 
                "Status": 1 
            } 
        }, { 
            "id": "a3", 
            "status": 201, 
            "body": { 
                "Id": { 
                    "Invoice": "001", 
                    "LineId": "0002" 
                }, 
                "Context": 2, 
                "Description": "Invoice line 2", 
                "Status": 1 
            } 
        } 
    ] 
}