Dimension Service API  2.0.0
api indexresource index

POST {+dimension}/aspects

since: 0.6
Creates a new Aspect within a Dimension. Aspects require a name identifier, unique among all other aspects in the same dimension, for use by external systems to refer to or access the aspect. Additionally, each aspect will be assigned a permanent, system-generated ID at the time of creation; however, it is an error to set the DimensionAspect.id field as a part of this operation.

Aspects support localized labels for human-readable descriptive text. Labels can be optionally set when creating a new aspect by populating the DimensionAspect.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.)

This is a privileged operation.

Path Elements

+dimension
0.6required
string
The URI path to a specific dimension (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

Resource Information

Request Content
json
Request Object
Response Content
json
Response Object
Success Statuses
201  CREATED
Error Statuses
400  BAD REQUEST
409  CONFLICT
Other Methods

Example - Creating a new aspect

Request:

{
  "name"  : "CITY",
  "labels": [
    {"locale": "en",    "value": "City"},
    {"locale": "en-GB", "value": "Township"},
    {"locale": "es",    "value": "ciudad"}
  ]
}

Response:
HTTP/1.1  201  CREATED 

{
  "id"    : "85921462-8431-3951-97c0-558f7b5f8ffc",
  "name"  : "CITY",
  "label" : {"locale": "en",    "value": "City"}
}

Error Example - the 'id' field cannot be assigned

see: DIM-001102

Request:

{
  "id"    : "abcdef00-1234-5678-9012-34567890abcd",
  "name"  : "CITY",
  "labels": [
    {"locale": "en",    "value": "City"},
    {"locale": "en-GB", "value": "Township"},
    {"locale": "es",    "value": "ciudad"}
  ]
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
  "errorID"     : "DIM-001102",
  "errorMessage": "Sorry, the 'id' field value cannot be pre-assigned when creating an aspect.",
  "requestID"   : "DIM-b7780800200c9a66",
  "details": [ {"fieldID": "id"} ]
}

Error Example - if the 'name' field is missing, empty, or only contains whitespace

see: DIM-001103

Request:

{
  "name"  : " ",
  "labels": [
    {"locale": "en",    "value": "City"},
    {"locale": "en-GB", "value": "Township"},
    {"locale": "es",    "value": "ciudad"}
  ]
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
  "errorID"     : "DIM-001103",
  "errorMessage": "Sorry, when creating an aspect 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

see: DIM-001104

Request:

{
  "name"  : "CITY",
  "labels": [
    {"locale": "en",    "value": "City"},
    {"locale": "en-GB", "value": "Township"},
    {"locale": "es",    "value": "ciudad"}
  ]
}

Response:
HTTP/1.1  409  CONFLICT 

{
  "errorID"     : "DIM-001104",
  "errorMessage": "Sorry, the name 'CITY' is already used by an existing aspect in the dimension.",
  "requestID"   : "DIM-b7780800200c9a66"
}

Error Example - missing request payload

Request:


                  Response:
HTTP/1.1 
                  400 
                  BAD REQUEST