Dimension Service API  2.0.0
api indexresource index

POST {+dimension}/nodes/search

since: 0.32
Searches all nodes within a specific dimension and returns a paged list of matching nodes. This endpoint supports sorting and more advanced functionality.

Path Elements

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

Query Parameters

page
0.32optional
string
The string representing the encoded page information from a previous result. This value is used for scrolling through the result pages.
ancestorId
0.32optional
string
The UUID of a node in the current dimension. If provided, the search returns only those nodes that declare an ancestor with this UUID (i.e., nodes that are descendant from a node with the given UUID).

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.
pros-dimension-include
0.17optional
string

pros-dimension-include is an optional HTTP header used for clients to indicate whether data values that are omitted by default should be returned by APIs of the PROS Dimension Service. Its value consists of one or more values as listed below. When multiple values are specified, the ASCII comma charater must be used as a separator. There is a trade-off between data completeness and service performance. Higher data completeness may result in lower availability and/or lower performance.

When node.ancestor.id is specified, a result set of a request that returns dimension nodes contains members exposing their ancestor node IDs as well as other properties.

When node.ancestor.name is specified, a result set of a request that returns dimension nodes contains members exposing their ancestor node names as well as other properties.

When node.aspect.name is specified, a result set of a request that returns dimension nodes contains members exposing their aspect names alongside their aspect IDs.

When node.label.allLocales is specified, a result set of a request that returns dimension nodes contains members exposing the whole list of labels corresponding to all available locales as well as other properties.

0.17 valid values:
  • node.ancestor.id
  • node.ancestor.name
  • node.aspect.name
  • node.label.allLocales

Resource Information

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

Example - Search using the query 'US-TX' and sort by names in ascending order

Request:

{
  "query": {
    "query": "US-TX"
  "options": {
    "pageSize": 50,
    "pageNumber" 1
  },
  "sort": {
    "field": "name",
    "order": "asc"
  }
}

Response:
HTTP/1.1  200  OK 

{
  "data": [
    {
      "aspect": {
        "aspectID": "85921462-8431-3951-97c0-558f7b5f8ffc"
      },
      "id": "d60abd09-f492-3902-8f35-5448709f18cc",
      "label": {
        "locale": "en",
        "value": "Austin"
      },
      "name": "US-TX-Austin"
    },
    {
      "aspect": {
        "aspectID": "2b848a8c-c886-3253-921a-77c43cd50aae"
      },
      "id": "4be24f04-a3b7-37dc-9573-ae1da864d3df",
      "label": {
        "locale": "en",
        "value": "Houston"
      },
      "name": "US-TX-Houston"
    }
  ],
  "meta": {
    "next": {
      "page": "AAAAAC8-kaDd_____w",
      "perPage": "50",
      "q": "US-TX"
    }
  }
}

Example - Search using the query 'US-TX' and sort by the 'POPULATION' attribute in descending order

Request:

{
  "query": {
    "query": "US-TX"
  "options": {
    "pageSize": 50,
    "pageNumber" 1
  },
  "sort": {
    "field": "POPULATION",
    "type": "integer",
    "order": "desc"
  }
}

Response:
HTTP/1.1  200  OK 

{
  "data": [
    {
      "aspect": {
        "aspectID": "2b848a8c-c886-3253-921a-77c43cd50aae"
      },
      "id": "4be24f04-a3b7-37dc-9573-ae1da864d3df",
      "label": {
        "locale": "en",
        "value": "Houston"
      },
      "name": "US-TX-Houston"
    },
    {
      "aspect": {
        "aspectID": "85921462-8431-3951-97c0-558f7b5f8ffc"
      },
      "id": "d60abd09-f492-3902-8f35-5448709f18cc",
      "label": {
        "locale": "en",
        "value": "Austin"
      },
      "name": "US-TX-Austin"
    }
  ],
  "meta": {
    "next": {
      "page": "AAAAAC8-kaDd_____w",
      "perPage": "50",
      "q": "US-TX"
    }
  }
}

Example - Search all nodes of a dimension by supplying a blank query string

Request:

{
  "query": {
    "query": ""
  },
  "options": {
    "pageSize": 5,
    "pageNumber": 1
  },
  "sort": {
    "field": "POPULATION",
    "type": "integer",
    "order": "desc"
  }
}

Response:
HTTP/1.1  200  OK 

{
    "data": [
        {
            "aspect": {
                "aspectID": "85921462-8431-3951-97c0-558f7b5f8ffc"
            },
            "id": "bb557c6a-9a5e-349b-8bda-645c09742f0b",
            "label": {
                "locale": "und",
                "value": "US-NY-New York"
            },
            "name": "US-NY-New York"
        },
        {
            "aspect": {
                "aspectID": "85921462-8431-3951-97c0-558f7b5f8ffc"
            },
            "id": "4b6a35ea-20f6-3e49-b731-dce1c90e9d3b",
            "label": {
                "locale": "und",
                "value": "US-CA-Los Angeles"
            },
            "name": "US-CA-Los Angeles"
        },
        {
            "aspect": {
                "aspectID": "85921462-8431-3951-97c0-558f7b5f8ffc"
            },
            "id": "fc5a6572-6743-30a4-9c24-7dae8c6acf6a",
            "label": {
                "locale": "und",
                "value": "US-IL-Chicago"
            },
            "name": "US-IL-Chicago"
        },
        ...
    ],
    "meta": {
        "next": {
            "page": "AAAAAgAAAAo",
            "perPage": "10",
            "q": ""
        }
    }
}}

Error Example - Missing 'query' object

see: DIM-007000

Request:

{
  "sort": {
    "field": "name",
    "order": "asc"
  },
  "options": {
      "pageSize": 50,
      "pageNumber": 1
  }
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
    "errorID": "DIM-007000",
    "errorMessage": "Sorry, the query object must be supplied as part of the search request.",
    "requestID": "DIM-7218413745509d38"
}

Error Example - Empty 'attribute' field

see: DIM-007002

Request:

{
  "query": {
    "query": "US-TX",
    "attribute": ""
  },
  "sort": {
    "field": "name",
    "order": "asc"
  },
  "options": {
      "pageSize": 50,
      "pageNumber": 1
  }
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
    "errorID": "DIM-007002",
    "errorMessage": "Sorry, the 'attribute' field cannot be blank.",
    "requestID": "DIM-32ba91c0747961ee"
}

Error Example - Missing or empty 'field' within the sort object

see: DIM-007003

Request:

{
  "query": {
    "query": "US-TX"
  },
  "sort": {
    "field": "",
    "order": "asc"
  },
  "options": {
      "pageSize": 50,
      "pageNumber": 1
  }
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
    "errorID": "DIM-007003",
    "errorMessage": "Sorry, the 'field' field within the sort object must be supplied and cannot be blank.",
    "requestID": "DIM-d45259e1dbbf9303"
}

Error Example - Missing or empty 'order' within the sort object

see: DIM-007004

Request:

{
  "query": {
    "query": "US-TX"
  },
  "sort": {
    "field": "name",
    "order": ""
  },
  "options": {
      "pageSize": 50,
      "pageNumber": 1
  }
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
    "errorID": "DIM-007004",
    "errorMessage": "Sorry, the 'order' field within the sort object must be supplied and cannot be blank.",
    "requestID": "DIM-40f07a7e81bf36a8"
}

Error Example - Invalid order value in the sort object

see: DIM-007005

Request:

{
  "query": {
    "query": "US-TX"
  },
  "sort": {
    "field": "name",
    "order": "invalid"
  },
  "options": {
      "pageSize": 50,
      "pageNumber": 1
  }
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
    "errorID": "DIM-007005",
    "errorMessage": "Sorry, the 'order' field within the sort object only accepts 'asc' or 'desc' as a valid value.",
    "requestID": "DIM-aa6aada25bc3b7b2"
}

Error Example - Invalid attribute type within the sort object

see: DIM-007006

Request:

{
  "query": {
    "query": "US-TX"
  },
  "sort": {
    "field": "name",
    "order": "asc",
    "type": "invalid"
  },
  "options": {
      "pageSize": 50,
      "pageNumber": 1
  }
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
    "errorID": "DIM-007006",
    "errorMessage": "Sorry, the 'type' field within the sort object is not a valid type. Valid types are 'base64', 'decimal', 'integer', 'percent', 'datetime', 'date', and 'text'.",
    "requestID": "DIM-6911b590440dda5d"
}

Error Example - Missing or blank locale within the sort object

see: DIM-007007

Request:

{
  "query": {
    "query": "US-TX"
  },
  "sort": {
    "field": "name",
    "order": "asc",
    "locale": ""
  },
  "options": {
      "pageSize": 50,
      "pageNumber": 1
  }
}

Response:
HTTP/1.1  400  BAD REQUEST 

{
    "errorID": "DIM-007007",
    "errorMessage": "Sorry, the 'locale' field within the sort object cannot be blank if it was supplied.",
    "requestID": "DIM-bf76c8cc88f3996"
}