Dimension Service API  2.0.0
api indexresource index

GET {+dimension}/nodes/name/{name}

since: 0.6
Returns a single object describing a specific node identified by its externally-provided name.

Path Elements

+dimension
0.6required
string
The URI path to a specific dimension (whether by ID or by name).
name
0.6required
string
The unique string name of the desired node, as used by external systems.

Query Parameters

attrID
0.6optional
string
Retrieves the node-specific value of the specified node attribute (given its system-generated ID) and includes it in the response, saving the cost of making one or more separate requests for the value(s) of a single attribute or all node attributes.

This parameter may be repeated, with different attribute IDs, to retrieve different attribute values for the same node in the same request. See the additional details in the resource description for more information.

example value

e0308bea-a8ee-3011-9a20-abfb85c136b6
attrName
0.6optional
string
Retrieves the node-specific value of the specified node attribute (given its externally-provided name) and includes it in the response, saving the cost of making one or more separate requests for the value(s) of a single attribute or all node attributes.

This parameter may be repeated, with different attribute IDs, to retrieve different attribute values for the same node in the same request. See the additional details in the resource description for more information.

example values

  • POPULATION
  • color
  • Size

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
Accept-Language
0.13optional
string
The Accept-Language request HTTP header advertises which languages the client is able to understand, and which locale variant is preferred.

Extended description

By default, retrieving a node does not retrieve its associated attribute values. If desired, attribute values may be requested by name or by ID (see: query parameters attrName and attrID, respectively). Requesting attributes by ID reduces the overhead cost associated with name resolution. Requesting the same attribute by both ID and name in the same request is redundant and not recommended. Repeated attributes in a request will be included only once in the response. Defined attributes that have no assigned value for this node, and that also do not define a default value, will not appear in the response. Requests for unknown attributes will cause an error.

Resource Information

Response Content
json
Response Object
Success Statuses
200  OK
Error Statuses
400  BAD REQUEST
Other Methods

Example 1

Request:

Response:
HTTP/1.1  200  OK 

{
  "id"    : "32b16534-406d-3436-b4c6-c61f24874650",
  "name"  : "US-TX-Houston",
  "label" : {"locale":"en", "value":"Houston"},
  "aspect": {"aspectID":"85921462-8431-3951-97c0-558f7b5f8ffc"},
  "ancestors" : [
    {
      "aspectID": "2b848a8c-c886-3253-921a-77c43cd50aae",
      "nodeID"  : "7baaa4ab-dd43-31a2-9454-ebc60fb910d5"
    },
    {
      "aspectID": "6ddc09dc-4560-31d9-854e-9fe670374eb2",
      "nodeID"  : "7516fd43-adaa-3e0b-8a65-a672c39845d2"
    }
  ]
}

Example - request attribute values by name

Request:

Response:
HTTP/1.1  200  OK 

{
  "id"        : "32b16534-406d-3436-b4c6-c61f24874650",
  "name"      : "US-TX-Houston",
  "label"     : {"locale":"en", "value":"Houston"},
  "aspect"    : {"aspectID":"85921462-8431-3951-97c0-558f7b5f8ffc"},
  "ancestors" : [
    {
      "aspectID": "2b848a8c-c886-3253-921a-77c43cd50aae",
      "nodeID"  : "7baaa4ab-dd43-31a2-9454-ebc60fb910d5"
    },
    {
      "aspectID": "6ddc09dc-4560-31d9-854e-9fe670374eb2",
      "nodeID"  : "7516fd43-adaa-3e0b-8a65-a672c39845d2"
    }
  ],
  "attributes": [
    {
      "attrID"  : "29be0fe0-8815-37d0-81b5-7f4781e3848e",
      "attrName": "POPULATION",
      "type"    : "integer",
      "integer" : "2076189",
      "text"    : "2,076,189"
    },
    {
      "attrID"  : "c689acc7-ee13-3482-aa7b-c6a13419421d",
      "attrName": "LAT",
      "type"    : "decimal",
      "decimal" : "29.7604",
      "text"    : "29.7604"
    },
    {
      "attrID"  : "c689acc7-ee13-3482-aa7b-c6a13419421e",
      "attrName": "LON",
      "type"    : "decimal",
      "decimal" : "-95.3698",
      "text"    : "-95.3698"
    }
  ]
}

Example - request attribute values by ID

Request:

Response:
HTTP/1.1  200  OK 

{
  "id"        : "32b16534-406d-3436-b4c6-c61f24874650",
  "name"      : "US-TX-Houston",
  "label"     : {"locale":"en", "value":"Houston"},
  "aspect"    : {"aspectID":"85921462-8431-3951-97c0-558f7b5f8ffc"},
  "ancestors" : [
    {
      "aspectID": "2b848a8c-c886-3253-921a-77c43cd50aae",
      "nodeID"  : "7baaa4ab-dd43-31a2-9454-ebc60fb910d5"
    },
    {
      "aspectID": "6ddc09dc-4560-31d9-854e-9fe670374eb2",
      "nodeID"  : "7516fd43-adaa-3e0b-8a65-a672c39845d2"
    }
  ],
  "attributes": [
    {
      "attrID"  : "c689acc7-ee13-3482-aa7b-c6a13419421d",
      "attrName": "LAT",
      "type"    : "decimal",
      "decimal" : "29.7604",
      "text"    : "29.7604"
    },
    {
      "attrID"  : "c689acc7-ee13-3482-aa7b-c6a13419421e",
      "attrName": "LON",
      "type"    : "decimal",
      "decimal" : "-95.3698",
      "text"    : "-95.3698"
    }
  ]
}

Error Example - node does not exist

see: DIM-001201

Request:

Response:
HTTP/1.1  400  BAD REQUEST 

{
  "errorID"     : "DIM-001201",
  "errorMessage": "Sorry, the requested dimension node 'US-TX-Houston' does not exist.",
  "requestID"   : "DIM-ab3332f82d70846b",
}

Error Example - requested attribute does not exist

see: DIM-001223

Request:

Response:
HTTP/1.1  400  BAD REQUEST 

{
  "errorID"     : "DIM-001223",
  "errorMessage": "Sorry, cannot retrieve a node with values for unknown attributes.
                   Please review the defined attributes and try again.",
  "requestID"   : "DIM-ab3332f82d70846a",
  "details"     : [
    {
      "errorID"     : "DIM-001401",
      "errorMessage": "Sorry, the requested attribute 'c689acc7-ee13-3482-aa7b-c6a13419421d' does not exist.",
      "fieldID"     : "attrID",
      "value"       : "c689acc7-ee13-3482-aa7b-c6a13419421d"
    },
    {
      "errorID"     : "DIM-001401",
      "errorMessage": "Sorry, the requested attribute 'LON' does not exist.",
      "fieldID"     : "attrName",
      "value"       : "LON"
    }
  ]
}