Search Published Categories
get
/content/published/api/v1.1/taxonomies/{id}/categories
Use this query to search published categories. You can control the number of categories to be fetched, paginated, and sorted. Additionally, this resource can fetch field values of matching items.
Query expression syntax supports conditions that match the field values. Query conditions can be joined by using AND/OR operators and grouped with parenthesis. Below are general examples of queries.
In general one form of filtering is supported by this resource.
Request Headers (Optional):
Query expression syntax supports conditions that match the field values. Query conditions can be joined by using AND/OR operators and grouped with parenthesis. Below are general examples of queries.
Query expression | ?q=(name co "car") |
Query expression usage with this resource | /published/api/v1.1/taxonomies/{id}/categories?q=(name co "car") |
In general one form of filtering is supported by this resource.
- Query all categories within a taxonomy: All categories of the taxonomy are queried. However, query conditions are limited to standard fields (id, name, parent.id) and/or optional fields (ancestors.id, ancestors.name, ancestors.apiName).
For example: /published/api/v1.1/taxonomies/{id}/categories?q=(id eq "B0A39B47122C4CE88A6CD52B90C15263")
Operator | Example | Supported data types | Description |
---|---|---|---|
eq | q=(id eq "B0A39B47122C4CE88A6CD52B90C15263") q=(name eq "Cars") q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB") q=(ancestors.id eq "C7117D407B1845DEAABBE00526D112FB") q=(ancestors.name eq "car") q=(ancestors.apiName eq "tax-c-c1") | text | Equals operator (eq) matches the exact value supplied in the query. The value provided with this operator is not case-sensitive (name) except for identifier fields (id, parent.id, ancestors.id). This operator considers even special characters in the value. |
co | q=(name co "car red") q=(ancestors.name co "car") | text | Contains operator (co) matches every word given in the criteria. It gives the results that have at least one of the words (in this example, car or red or both). This operator does not consider special characters in the value while searching. This operator is applicable to text in case of single-valued attributes. The value provided with this operator is not case-sensitive. |
sw | q=(name sw "Car") q=(ancestors.name sw "ca") | text | Starts With operator (sw) matches only the initial character values given in the field condition. The value provided with this operator is not case-sensitive. |
Request Headers (Optional):
Header Name | Header Value |
---|---|
channelToken | {valid channel token value} |
Accept | application/json |
Request
Path Parameters
-
id: string
Unique identifier (ID) of a taxonomy.
Query Parameters
-
channelToken(optional): string
Channel token of the publish target. A channel token must be provided as either a query parameter or a request header.
-
fields(optional): string
The fields parameter is used to control the returned fields and values in the queried category. This parameter accepts a comma-separated list of field names or all. These fields will be returned for each queried category. As all the field names are case-sensitive, users must provide the correct field names in the search query. When fields is specified as all (case-insensitive), all the standard fields and optional fields are returned for each category. Each category has both standard fields (id, name, description, parent) and optional fields (ancestors, children). The standard field id is always returned in the response and cannot be filtered out. This parameter is optional in the query and by default query result shows only id, name and description in the response. Any incorrect or invalid field name given will result in an error.
Example: ?q=(name co "car")&fields=name,description,parent,ancestors
This returns id, name, description, parent and ancestors in the search results for a category containing "car" in the name field.
Example: ?fields=name,parent
This will return only standard fields (such as id, name and parent) for all categories within the default limit.
Example: ?fields=name,children
This will return only id, name and the children count for all categories within the default limit.
Default Value:name,description
-
limit(optional): integer(int32)
This parameter accepts a non negative integer and is used to control the size of the result. The maximum value allowed for limit is 500.Default Value:
100
-
links(optional): string
Accepts a comma-separated list of rel (relation) links, which the client requires in the results. By default, all the applicable links in a resource are included in the response. Possible values are: self, canonical, describedby, first, last, prev, next.
Example: links=self,canonical will only return the links with the rel property self or canonical. -
offset(optional): integer(int32)
Start index of response rows.Default Value:
0
-
orderBy(optional): string
The orderBy parameter is used to control the order (ascending or descending) of queried items. This parameter is optional in the query and by default there is no order of results. This parameter accepts field names separated by a colon (:), which the user wants to sort the results and sort order.
format: orderBy={fieldName}:{asc/des} (*Note: asc stands for ascending and des for descending. asc and des are always in lower case.)
In a category query, fieldName can be name or position (standard field). When sorting results by position it is important to remember that only searches by parent.id can actually benefit from it. The category position is unique only within a given level or under a given parent category. There will be different categories with the same position value at different levels of the taxonomy. The sort order is optional and by default it is ascending. Any incorrect or invalid field name given will result in an error.
Example: orderBy=name:asc
Returns all categories in ascending order of name.
Example: orderBy=name:des
Returns all categories in descending order of name.
Example: orderBy=position:asc
Returns all categories in ascending order of position.
Example: orderBy=position:des
Returns all categories in descending order of position. -
q(optional): string
This parameter accepts a query expression condition that matches the field values. Many such query conditions can be joined using AND/OR operators and grouped with parentheses. The value of query condition follows the format of {fieldName} {operator} "{fieldValue}". The only values allowed in the operator are eq (Equals), co (Contains) and sw (Startswith).
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name eq "Furnitures")
This will return all categories matching exactly the name "Furnitures".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name co "chairs" OR name co "red")
This will return all categories containing the words "chairs" or "red".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name sw "cars")
This will return all categories which name start with "cars".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(apiName eq "cars-apiname")
This will return all categories which apiName matches "cars-apiname".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(id eq "B0A39B47122C4CE88A6CD52B90C15263")
This will return a category with the given identifier.
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.id eq "B0A39B47122C4CE88A6CD52B90C15263")
This will return the categories with an ancestor with the given identifier.
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name eq "Furnitures")
This will return all categories with an ancestor matching exactly the name "Furnitures".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name co "chairs" OR ancestors.name co "red")
This will return all categories with an ancestor containing the words "chairs" or "red".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name sw "cars")
This will return all categories with an ancestor which name starts with "cars".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.apiName eq "cars-apiname")
This will return all categories which apiName matches "cars-apiname".
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB")&orderBy=position:asc
This will return all children categories underneath the given parent identifier sorted by their position in ascending order.
Example:
https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB" AND name co "blue")
This will return all children categories underneath the given parent identifier which contains the word "blue" in their names. -
totalResults(optional): boolean
Accepts a Boolean value. Setting it to true displays the total results field in the response.Default Value:
false
Response
Supported Media Types
- application/json
200 Response
Successful operation.
Root Schema : CollectionProperties
Type:
object
CollectionProperties.
Show Source
-
aggregationResults(optional):
array aggregationResults
Aggregation results.
-
count(optional):
integer(int32)
Total number of records in the current response.
-
hasMore(optional):
boolean
Check whether there are more pages to fetch.
-
items(optional):
array items
Singular resources contained in the collection.
-
limit(optional):
integer(int32)
Actual page size used by the server. This might not be the same as what the client requests.
-
links(optional):
array links
Links of the resource.
-
offset(optional):
integer(int32)
The actual index from which the singular resources are returned.
-
pinned(optional):
array pinned
Pinned items. Shows items pinned at the top of search list
-
properties(optional):
object properties
Additional Properties Allowed: additionalPropertiesadditional collection properties.
-
scrollId(optional):
string
scrollId if the search resolved to a scroll search.
-
totalResults(optional):
integer(int32)
Total number of rows that satisfy the client request (excluding the paging parameters.)
Nested Schema : links
Type:
array
Links of the resource.
Show Source
-
Array of:
object Link
Link of the resource.
Nested Schema : pinned
Type:
array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : properties
Type:
object
Additional Properties Allowed
Show Source
additional collection properties.
Nested Schema : items
Type:
object
Nested Schema : Link
Type:
object
Link of the resource.
Show Source
-
href(optional):
string
The target resource's URI. It could be template URI. It is a required property in the get response.
-
mediaType(optional):
string
Media type.
-
method(optional):
string
What HTTP method can be used to access the target resource.
-
profile(optional):
string
Link to the metadata that describes the target resource.
-
rel(optional):
string
Relation type. It is a required property in the get response.
-
templated(optional):
boolean
Whether the URI is a template.
Nested Schema : additionalProperties
Type:
object
400 Response
Bad Request. The server is unable to process the request on the client side due to malformed syntax, invalid data or message framing.
403 Response
Forbidden. Client is not authorized to perform this request.
500 Response
Internal server error. An unexpected error condition encountered in the system.
Examples
The following example shows how to search published taxonomy categories.
curl -i -X GET -H "Accept:application/json" 'http://<hostname>/content/published/api/v1.1/taxonomies/{id}/categories'
Example 1
Searches published taxonomy category with taxonomy id: 26950D77A5654D8BA407AC9F7DBCFF1F, having category id: 2069018ECE874C2DAA4051E9C16AD244 with channelToken: 1a3885a5a75b40baafe6495eb0b1125b.
/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=%28+id+eq+%222069018ECE874C2DAA4051E9C16AD244%22%29&totalResults=true&offset=0&orderBy=name%3Aasc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all
Response Body
{ ody": { "hasMore": false, "offset": 0, "count": 1, "limit": 1, "totalResults": 1, "items": [ { "apiName": "t31-c-c-c1", "id": "2069018ECE874C2DAA4051E9C16AD244", "name": "car red medium", "description": "car red medium description", "position": 1, "parent": { "id": "50AE00A8234B4AE1B675D36989F8B9CF", "name": "car red", "apiName": "t31-c-c" }, "ancestors": [ { "id": "6775D3D56E184CC3B8EC59A32AF1DD73", "name": "car", "apiName": "t31-c" }, { "id": "50AE00A8234B4AE1B675D36989F8B9CF", "name": "car red", "apiName": "t31-c-c" } ], "links": [ { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories/2069018ECE874C2DAA4051E9C16AD244?channelToken=1a3885a5a75b40baafe6495eb0b1125b", "rel": "self", "method": "GET", "mediaType": "application/json" } ] } ], "links": [ { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all", "rel": "self", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all", "rel": "canonical", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/published/api/v1.1/metadata-catalog/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?channelToken=1a3885a5a75b40baafe6495eb0b1125b", "rel": "describedby", "method": "GET", "mediaType": "application/schema+json" }, { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all", "rel": "first", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all", "rel": "last", "method": "GET", "mediaType": "application/json" }
Example 2
This searches published taxonomy categories with taxonomy id: 26950D77A5654D8BA407AC9F7DBCFF1F, with category name equals to car blue with channelToken:1a3885a5a75b40baafe6495eb0b1125b
/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=%28+name+eq+%22car+blue%22%29&totalResults=true&offset=0&orderBy=name%3Aasc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all
Response Body
{ "hasMore": false, "offset": 0, "count": 1, "limit": 1, "totalResults": 1, "items": [ { "apiName": "t31-car-blue-26950d77a5654d8ba407ac9f7dbcff1f", "id": "5096C5762F9540BCB23AA13001CA872E", "name": "car blue", "description": "car description", "position": 1, "parent": { "id": "6775D3D56E184CC3B8EC59A32AF1DD73", "name": "car", "apiName": "t31-c" }, "ancestors": [ { "id": "6775D3D56E184CC3B8EC59A32AF1DD73", "name": "car", "apiName": "t31-c" } ], "links": [ { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories/5096C5762F9540BCB23AA13001CA872E?channelToken=1a3885a5a75b40baafe6495eb0b1125b", "rel": "self", "method": "GET", "mediaType": "application/json" } ] } ], "links": [ { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all", "rel": "self", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all", "rel": "canonical", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/published/api/v1.1/metadata-catalog/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?channelToken=1a3885a5a75b40baafe6495eb0b1125b", "rel": "describedby", "method": "GET", "mediaType": "application/schema+json" }, { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all", "rel": "first", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all", "rel": "last", "method": "GET", "mediaType": "application/json" } ] } } ]