Dimension Service API  2.0.0
api indexresource index

POST {+dimensionAspect}/nodes/batch

since: 0.21
Batch operation to create multiple new dimension nodes within a specified aspect.

This is a privileged operation.

Path Elements

+dimensionAspect
0.21required
string
The URI path to a specific dimension aspect (whether by ID or by name).

Request Headers

pros-dimension-consistency
0.13optional
string
pros-dimension-consistency is an optional HTTP header used to define the data consistency level of the request. There is a trade off between data consistency and service availability and performance: higher data consistency can result in lower availability and slower performance, while lower data consistency can result in higher availability and faster performance.
0.13 valid values:
  • HIGHEST
  • HIGH
  • NORMAL
  • LOW
  • LOWEST

Extended description

The length of the response's nodes array is guaranteed to be exactly the same as the length of the request's nodes array. Furthermore, the order of elements in the response's nodes array is guaranteed to be exactly the same as the order of corresponding reference elements in the request's nodes array.

The same restrictions apply to each node in the request, as would apply when calling the non-batch create request with the same node. In particular:

The request's nodes array must contain between 1 and 100 nodes, inclusive. Any other size results in an error.

Note that a single large batch is not necessarily the most optimal request. Smaller batches that are sent in parallel on multiple connections will generally perform better than a single maximally-sized request. Ideal performance optimization needs to weigh the trade-off between batch size and request volume.

The response header pros-batch-errors indicates the number of elements with errors in the response body. This header is only returned when the status code is 200 and errors are present in the response, otherwise the header is omitted.

Resource Information

Request Content
json
Request Object
Response Content
json
Response Object
Success Statuses
200  OK
Error Statuses
400  BAD REQUEST
413  REQUEST ENTITY TOO LARGE

Example - Request to create multiple new nodes in the same aspect

Request:

{
  "nodes": [
    {
      "name": "US-TX-HOUSTON",
      "labels": [{ "locale": "en", "value": "Houston" }],
      "ancestors": [
        { "aspectName": "COUNTRY", "nodeName": "US" },
        { "aspectName": "STATE", "nodeName": "US-TX" }
      ]
    },
    {
      "name": "US-IL-CHICAGO",
      "ancestors": [
        { "aspectName": "COUNTRY", "nodeName": "US" },
        { "aspectName": "STATE", "nodeName": "US-IL" }
      ]
    },
    {
      "name": "US-TX-DALLAS",
      "ancestors": [
        { "aspectName": "COUNTRY", "nodeName": "US" },
        { "aspectName": "STATE", "nodeName": "US-TX" }
      ]
    }
  ]
}

Response:
HTTP/1.1  200  OK 

{
  "nodes": [
    {
      "node": {
        "id": "e5553498-2803-11e9-b210-d663bd873d93",
        "name": "US-TX-HOUSTON",
        "labels": [{ "locale": "en", "value": "Houston" }],
        "ancestors": [
          { "aspectName": "COUNTRY", "nodeName": "US" },
          { "aspectName": "STATE", "nodeName": "US-IL" }
        ]
      }
    },
    {
      "node": {
        "id": "9c27cd16-2804-11e9-b210-d663bd873d93",
        "name": "US-IL-CHICAGO",
        "ancestors": [
          { "aspectName": "COUNTRY", "nodeName": "US" },
          { "aspectName": "STATE", "nodeName": "US-IL" }
        ]
      }
    },
    {
      "error": {
        "errorID": "DIM-001204",
        "errorMessage": "The name 'US-TX-DALLAS' is already used by an existing node."
      }
    }
  ]
}

Example - Request node DTOs are invalid for this operation

Request:

{
  "nodes": [
    {
      "labels": [{ "locale": "en", "value": "Houston" }],
      "ancestors": [
        { "aspectName": "COUNTRY", "nodeName": "US" },
        { "aspectName": "STATE", "nodeName": "US-TX" }
      ]
    },
    {
      "name": "US-IL-CHICAGO",
      "id": "9c27cd16-2804-11e9-b210-d663bd873d93",
      "ancestors": [
        { "aspectName": "COUNTRY", "nodeName": "US" },
        { "aspectName": "STATE", "nodeName": "US-IL" }
      ]
    },
    {
      "name": "US-TX-DALLAS",
      "aspect": { "aspectName": "CITY" },
      "ancestors": [
        { "aspectName": "COUNTRY", "nodeName": "US" },
        { "aspectName": "STATE", "nodeName": "US-TX" }
      ]
    }
  ]
}

Response:
HTTP/1.1  200  OK 

{
  "nodes": [
    {
      "error": {
        "fieldID": "name",
        "errorID": "DIM-001203",
        "errorMessage": "When creating a dimension node the 'name' field must not be missing or blank."
      }
    },
    {
      "error": {
        "fieldID": "id",
        "errorID": "DIM-001202",
        "errorMessage": "The 'id' field cannot be pre-assigned when creating a dimension node."
      }
    },
    {
      "error": {
        "fieldID": "aspect",
        "errorID": "DIM-001206",
        "errorMessage": "The 'aspect' field must not be present when creating a dimension node."
      }
    }
  ]
}

Error Example - Request containing null node

Request:

{
  "nodes": [
    { "name": "US-TX-HOUSTON" },
    { "name": "US-IL-CHICAGO" },
    null,
    { "name": "US-WA-SEATTLE" }
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
  "errorID": "DIM-005205",
  "requestID":"DIM-cb0a3726b6756be1",
  "errorMessage": "Could not process the batch request because the request payload was missing or corrupt."
}

Error Example - Too many nodes in one request

Request:

{
  "nodes": [
    { "name": "US-TX-HOUSTON" },
    { "name": "US-IL-CHICAGO" },
    // ... 98 other nodes ...
    { "name": "US-WA-SEATTLE" }
  ]
}

Response:
HTTP/1.1  413  REQUEST ENTITY TOO LARGE 

{
  "errorID": "DIM-005413",
  "requestID":"DIM-3258b42d9a435122",
  "errorMessage": "The requested operation is limited to 100 items.  Please reduce the batch size and try again."
}