Creates a new dimension node within a specific aspect. Nodes require a
name identifier, unique among all other
nodes in the same dimension, for use by external systems to refer to or access the node.
Additionally, each node will be assigned a permanent, system-generated ID at the time of
creation; however, it is an error to set the
id field as a part of this operation. Since
the parent aspect is specified as part of the URI path, the
aspect field must also be
omitted from this operation.
Nodes support localized labels for human-readable descriptive text. Labels can
be optionally set when creating a new node by populating the
labels field with labels for zero
or more unique languages/locales. (Note: labels for locales whose base languages are not
configured in the parent dimension may be ignored.)
Both the labels and
ancestors fields can be omitted;
however at this time an API for updating the labels and ancestors for an existing dimension
node is not available.
This is a privileged operation.
Path Elements
| +dimensionAspect
string
|
The URI path to a specific dimension aspect (whether
by ID or
by name).
|
Example
- Adding a new dimension node to the CITY aspect
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY", "nodeName":"US"},
{"aspectName":"STATE", "nodeName":"US-TX"}
]
}
Response:
HTTP/1.1
201
CREATED
{
"id" : "32b16534-406d-3436-b4c6-c61f24874650",
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY", "nodeName":"US"},
{"aspectName":"STATE", "nodeName":"US-TX"}
]
}
Example
- Adding a new dimension node to the CITY aspect, ancestors identified using system IDs instead of by name
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectID":"6ddc09dc-4560-31d9-854e-9fe670374eb2", "nodeID":"7516fd43-adaa-3e0b-8a65-a672c39845d2"},
{"aspectID":"2b848a8c-c886-3253-921a-77c43cd50aae", "nodeID":"7baaa4ab-dd43-31a2-9454-ebc60fb910d5"}
]
}
Response:
HTTP/1.1
201
CREATED
{
"id" : "32b16534-406d-3436-b4c6-c61f24874650",
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectID":"6ddc09dc-4560-31d9-854e-9fe670374eb2", "nodeID":"7516fd43-adaa-3e0b-8a65-a672c39845d2"},
{"aspectID":"2b848a8c-c886-3253-921a-77c43cd50aae", "nodeID":"7baaa4ab-dd43-31a2-9454-ebc60fb910d5"}
]
}
Example
- Adding a new dimension node to the CITY aspect, no labels or ancestors defined
Request:
{
"name" : "US-TX-Houston"
}
Response:
HTTP/1.1
201
CREATED
{
"id" : "32b16534-406d-3436-b4c6-c61f24874650",
"name" : "US-TX-Houston",
"labels" : [],
"ancestors": []
}
Error
Example
- the 'id' field cannot be assigned
Request:
{
"id" : "abcdef00-1234-5678-9012-34567890abcd",
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY", "nodeName":"US"},
{"aspectName":"STATE", "nodeName":"US-TX"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001202",
"errorMessage": Sorry, the 'id' field value cannot be pre-assigned when creating a dimension node.",
"requestID" : "DIM-b7780800200c9a66",
"details" : [ {"fieldID": "id"} ]
}
Error
Example
- the 'aspect' field cannot be assigned (aspect specified in URI path)
Request:
{
"aspect" : {"aspectName":"CITY"},
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY", "nodeName":"US"},
{"aspectName":"STATE", "nodeName":"US-TX"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001206",
"errorMessage": Sorry, the 'aspect' field value cannot be assigned when creating a dimension node.",
"requestID" : "DIM-b7780800200c9a66",
"details" : [ {"fieldID": "aspect"} ]
}
Error
Example
- if the 'name' field is missing, empty, or only contains whitespace
Request:
{
"name" : " ",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY", "nodeName":"US"},
{"aspectName":"STATE", "nodeName":"US-TX"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001203",
"errorMessage": "Sorry, when creating a dimension node the 'name' field must not be missing or blank.",
"requestID" : "DIM-b7780800200c9a66",
"details" : [ {"fieldID": "name"} ]
}
Error
Example
- if the new 'name' is already in use
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY", "nodeName":"US"},
{"aspectName":"STATE", "nodeName":"US-TX"}
]
}
Response:
HTTP/1.1
409
CONFLICT
{
"errorID" : "DIM-001204",
"errorMessage": "Sorry, the name 'US-TX-HOUSTON' is already used by an existing dimension node.",
"requestID" : "DIM-b7780800200c9a66"
}
Error
Example
- missing request payload
Request:
Response:
HTTP/1.1
400
BAD REQUEST
Error
Example
- if an ancestor aspect does not exist
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"ASPECT_UNKNOWN", "nodeName":"US"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001214",
"errorMessage": "Sorry, the new node could not be created because
it referred to an ancestor in an unknown aspect: ASPECT_UNKNOWN",
"requestID" : "DIM-b7780800200c9a66"
}
Error
Example
- if an ancestor aspect is missing
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"nodeName":"US"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001212",
"errorMessage": "Sorry, when specifying an ancestor for dimension node 'US-TX-Houston', either the ancestor 'aspectID' or 'aspectName' field must be included in the request (both fields must not be missing or blank).",
"requestID" : "DIM-b7780800200c9a66"
}
Error
Example
- if an ancestor node does not exist
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY", "nodeName":"NODE_UNKNOWN"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001215",
"errorMessage": "Sorry, the new node could not be created because
it referred to an unknown ancestor node: NODE_UNKNOWN",
"requestID" : "DIM-b7780800200c9a66"
}
Error
Example
- if an ancestor node is missing
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001213",
"errorMessage": "Sorry, when specifying an ancestor for dimension node 'US-TX-Houston', either the ancestor 'nodeID' or 'nodeName' field must be included in the request (both fields must not be missing or blank).",
"requestID" : "DIM-b7780800200c9a66"
}
Error
Example
- if an ancestor node does not belong to ancestor aspect
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"COUNTRY", "nodeName" : "US-TX"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001208",
"errorMessage": "Sorry, the ancestor node 'US-TX' does not belong to ancestor aspect 'COUNTRY'.",
"requestID" : "DIM-b7780800200c9a66"
}
Error
Example
- if an ancestor belongs to same aspect as the new node
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"CITY", "nodeName" : "US-CA-Los Angeles"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001209",
"errorMessage": "Sorry, dimension node 'US-TX-Houston' cannot refer to an ancestor node 'US-CA-Los Angeles' within its own aspect 'CITY'.",
"requestID" : "DIM-b7780800200c9a66"
}
Error
Example
- if two or more ancestors belong to same aspect
Request:
{
"name" : "US-TX-Houston",
"labels" : [{"locale":"en", "value":"Houston"}],
"ancestors":[
{"aspectName":"STATE", "nodeName" : "US-TX"},
{"aspectName":"STATE", "nodeName" : "US-CA"}
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001211",
"errorMessage": "Sorry, dimension node 'US-TX-Houston' can contain at most one ancestor for aspect 'STATE'.",
"requestID" : "DIM-b7780800200c9a66"
}
Error
Example
- if ancestor references root node
Request:
{
"name" : "US",
"labels" : [{"locale":"en", "value":"United States"}],
"ancestors":[
{ "aspectName" : "WORLD", "nodeName" : "ANY" }
]
}
Response:
HTTP/1.1
400
BAD REQUEST
{
"errorID" : "DIM-001210",
"errorMessage": "Sorry, cannot set ancestor relationships for the root aspect 'WORLD'.",
"requestID" : "DIM-b7780800200c9a66"
}