Read a taxonomy
/content/management/api/v1.1/taxonomies/{id}
Request
-
id: string
id of the taxonomy.
-
fields(optional): string
This parameter is used to control the returned fields for a taxonomy. This parameter accepts a comma-separated list of field names or all. These fields will be returned for each taxonomy in the list. As all the field names are case-sensitive, users must provide the correct field names in the query. Each taxonomy has both standard fields (id, name, description, shortName, status, version, isPublishable, isForSiteManagement, customProperties, createdBy, createdDate, updatedBy, updatedDate) and additional fields (availableStates, publishedChannels, categoryProperties and roleName). When fields is specified as all (case-insensitive), all the standard and additional fields are returned. The standard fields are always returned in the response and cannot be filtered out. Taxonomy in "draft" state will not have a version. Users can only filter out the additional fields. Users cannot expand the categoryProperties sub-resource while reading a taxonomy but a link to the sub-resource API will be returned. This parameter is optional in the query and by default result shows only standard fields in the response. Any incorrect or invalid field name given in the query will result in error.
This returns all standard fields along with the additional field availableStates for each taxonomy.
Example: ?fields=availableStates
This returns all standard fields along with the additional fields availableStates and publishedChannels for each taxonomy.
Example: ?fields=availableStates,publishedChannels
This returns all standard fields along with all additional fields (availableStates and publishedChannels) and a link to the sub-resource categoryProperties for each taxonomy.
Example: ?fields=all
-
links(optional): string
This parameter accepts a comma-separated list of link names. By default, this parameter gives all the links applicable. Possible values are: self, canonical, describedby
-
q(optional): string
This parameter accepts a query expression condition that matches the field values. Query conditions can be joined using AND operators and grouped with parentheses. The value of a query condition follows the format of {fieldName} {operator} "{fieldValue}". The only field names allowed are status, version, name, shortName, roleName and repositoryId. A query cannot include multiple status, version, name, shortName, roleName or repositoryId fieldNames. Both name and shortName cannot be specified in the same query.
If no value is provided for status it defaults to "promoted". When listing taxonomies, status can be equal to "draft", "promoted" or "all". When listing taxonomies, roleName can be equal to "viewer", "editor" or "manager". If status is equals to "all", all taxonomies will be retrieved - if a taxonomy is currently available in both "draft" and "promoted" states, only "draft" will be returned. In case status equals to "all" is used in other endpoints, an error will be returned.
The only value allowed in the operator is eq (Equals) for status, version, shortName, roleName and repositoryId.
The only value allowed in the operator is co (Contains) for name.
When updating a taxonomy the query parameter should always be provided with status set to "draft" as the default status is "promoted" and a promoted taxonomy cannot be modified.
Example:
https://{cecsdomain}/content/management/api/v1.1/taxonomies?q=(status eq "draft")
Example:
https://{cecsdomain}/content/management/api/v1.1/taxonomies?q=(status eq "promoted")
Response
- application/json
200 Response
object
-
availableStates(optional):
array availableStates
List all states of the Taxonomy. This is an optional property and is only returned if requested in the fields parameter. It is ignored in post/put requests.
-
categoryProperties(optional):
object ItemSubResourceListCategoryPropertyDefinition
Item SubResource.
-
createdBy(optional):
string
The user who created the Taxonomy.
-
createdDate(optional):
object date
date
-
customProperties(optional):
object customProperties
Additional Properties Allowed: additionalPropertiesCustom properties of the Taxonomy. This consists of a name value pairs defined by the user. Single entries cannot be updated, the entire list of custom properties have to be provided to update entries.
-
description(optional):
string
The description of the Taxonomy.
-
id:
string
The id of the Taxonomy. This is a required property in the get response and ignored in post/put requests.
-
isForSiteManagement(optional):
boolean
Whether taxonomy is for site management. A site management taxonomy is not publishable. (defaults to false)
-
isPublishable(optional):
boolean
Whether taxonomy is publishable. (defaults to false)
-
links(optional):
array links
Links
-
name:
string
The name of the Taxonomy. It is a required property in the get response and cannot be empty in post/put request.
-
publishedChannels(optional):
array publishedChannels
Read Only:
true
Taxonomy published channels. -
roleName(optional):
string
name of the role on the resource.
-
shortName(optional):
string
The short name of the Taxonomy. This property is unique among all taxonomies and it is required in the get response. Up to 3 characters can be provided in a put/post request. If no value is provided, a default one will be generated.
-
status(optional):
string
Allowed Values:
[ "draft", "promoted" ]
The status of the Taxonomy. This is a required property in the get response and ignored in post/put requests. -
updatedBy(optional):
string
The user who last updated the Taxonomy.
-
updatedDate(optional):
object date
date
-
version(optional):
integer(int32)
Minimum Value:
1
The version of this Taxonomy. Version information is only returned for promoted taxonomies. It is ignored in post/put requests.
array
-
Array of:
object TaxonomyStatus
TaxonomyStatus
object
object
array
true
-
Array of:
object ChannelInTaxonomy
ChannelInTaxonomy
array
-
Array of:
object CategoryPropertyDefinition
Category Property Definition
object
-
apiName(optional):
string
Read Only:
true
Minimum Length:1
Maximum Length:64
API Name of the property. -
createdBy(optional):
string
Read Only:
true
The user who created the property. -
createdDate(optional):
object date
date
-
defaultValues(optional):
array defaultValues
Default values for the property.
-
description(optional):
string
Minimum Length:
0
Maximum Length:128
Description of the property. -
displayName:
string
Minimum Length:
1
Maximum Length:128
Display name of the property. -
id(optional):
string
Read Only:
true
id of the property. It is required in the GET response and PATCH request whereas it will be ignored in the POST request. -
isPublishable(optional):
boolean
Is the property publishable.
-
isSystemManaged(optional):
boolean
Read Only:
true
Is the property managed by the system. -
links(optional):
array links
Links
-
settings:
object PropertySettingsBean
-
updatedBy(optional):
string
Read Only:
true
The user who last updated the property. -
updatedDate(optional):
object date
date
-
valueCount:
string
Allowed Values:
[ "single", "list" ]
Value count as a single or list.
object
-
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.
object
-
customValidators(optional):
array customValidators
Custom validators for the property value.
-
editor(optional):
object PropertySettingsEditorBean
-
valueCountRange(optional):
object PropertySettingsValueCountRangeBean
object
-
name(optional):
string
Name of the editor.
-
options(optional):
object options
Additional Properties Allowed: additionalPropertiesOptions of the property value.
object
-
max(optional):
integer(int32)
Minimum Value:
1
Maximum count of the property value. -
min(optional):
integer(int32)
Minimum Value:
0
Minimum count of the property value.
object
-
options(optional):
object options
Additional Properties Allowed: additionalPropertiesValidator details.
-
type(optional):
string
Allowed Values:
[ "length" ]
Type of the validator.
object
object
object
object
-
id(optional):
string
id of the channel.
-
name(optional):
string
Name of the channel.
304 Response
400 Response
403 Response
404 Response
500 Response
Examples
The following examples show how to get a specific taxonomy based on its ID by submission of a GET request using cURL:
curl -X GET -H 'Accept: application/json' 'https://host:port/content/management/api/v1.1/taxonomies/{id}'
Example 1:
This returns the promoted (default) taxonomy based on its ID.
/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950
Response Body
{ "id": "5D5AF080B7824C49950443A7D51DE950", "name": "Taxonomy 1", "description": "", "shortName": "T1", "status": "promoted", "version": 4, "isPublishable": false, "isForSiteManagement": false, "createdBy": "cecusername", "createdDate": { "value": "2019-01-31T19:52:45.472Z", "timezone": "UTC" }, "updatedBy": "cecusername", "updatedDate": { "value": "2019-02-01T17:49:43.854Z", "timezone": "UTC" }, "links": [ { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950", "rel": "self", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950", "rel": "canonical", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/metadata-catalog/taxonomies/5D5AF080B7824C49950443A7D51DE950", "rel": "describedby", "method": "GET", "mediaType": "application/schema+json" } ] }
Example 2:
This returns the draft taxonomy associated with the ID 5D5AF080B7824C49950443A7D51DE950.
/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?q=(status eq \"draft\")
Response Body
{ "id": "5D5AF080B7824C49950443A7D51DE950", "name": "Taxonomy 1", "description": "", "shortName": "T1", "status": "draft", "isPublishable": false, "isForSiteManagement": false, "createdBy": "cecusername", "createdDate": { "value": "2019-02-01T17:50:09.286Z", "timezone": "UTC" }, "updatedBy": "cecusername", "updatedDate": { "value": "2019-02-01T17:50:09.286Z", "timezone": "UTC" }, "links": [ { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?q=(status eq \"draft\")", "rel": "self", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?q=(status eq \"draft\")", "rel": "canonical", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/metadata-catalog/taxonomies/5D5AF080B7824C49950443A7D51DE950", "rel": "describedby", "method": "GET", "mediaType": "application/schema+json" } ] }
Example 3:
This returns the availableStates
field, which is optional, in the response for a particular taxonomy.
/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=availableStates
Response Body
{ "id": "5D5AF080B7824C49950443A7D51DE950", "name": "Taxonomy 1", "description": "", "shortName": "T1", "status": "promoted", "version": 4, "isPublishable": false, "isForSiteManagement": false, "availableStates": [ { "status": "promoted", "version": 4, "published": false }, { "status": "draft", "published": false } ], "createdBy": "cecsusername", "createdDate": { "value": "2019-01-31T19:52:45.472Z", "timezone": "UTC" }, "updatedBy": "cecsusername", "updatedDate": { "value": "2019-02-01T17:49:43.854Z", "timezone": "UTC" }, "links": [ { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=availableStates", "rel": "self", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=availableStates", "rel": "canonical", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/metadata-catalog/taxonomies/5D5AF080B7824C49950443A7D51DE950", "rel": "describedby", "method": "GET", "mediaType": "application/schema+json" } ] }
Example 4:
This returns all standard fields, optional fields, and a link to the sub-resource categoryProperties
in the response for the taxonomy.
/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=all
Response Body
{ "id": "5D5AF080B7824C49950443A7D51DE950", "name": "Taxonomy 1", "description": "", "shortName": "T1", "status": "promoted", "version": 4, "roleName": "manager", "isPublishable": true, "isForSiteManagement": false, "availableStates": [ { "status": "promoted", "version": 4, "published": true }, { "status": "draft", "published": false } ], "publishedChannels": [ { "id": "CC59073EACA4A56A990700ADEB643CAB64E62AA2CC55", "name": "Channel 02" }, { "id": "CCD608830CFD886E62FC58DC2B89320BEA5A4052D0FC", "name": "Channel 01" } ], "createdBy": "cecsusername", "createdDate": { "value": "2019-01-31T19:52:45.472Z", "timezone": "UTC" }, "updatedBy": "cecsusername", "updatedDate": { "value": "2019-02-01T17:49:43.854Z", "timezone": "UTC" }, "categoryProperties": { "links": [ { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950/categoryProperties", "rel": "self", "method": "GET", "mediaType": "application/json" } ] }, "links": [ { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=all", "rel": "self", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=all", "rel": "canonical", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/metadata-catalog/taxonomies/5D5AF080B7824C49950443A7D51DE950", "rel": "describedby", "method": "GET", "mediaType": "application/schema+json" } ] }
Example 5:
This returns standard fields and a link to the sub-resource categoryProperties
in the response for the taxonomy.
/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=categoryProperties
Response Body
{ "id": "5D5AF080B7824C49950443A7D51DE950", "name": "Taxonomy 1", "description": "", "shortName": "T1", "status": "promoted", "version": 4, "isPublishable": false, "isForSiteManagement": false, "createdBy": "cecsusername", "createdDate": { "value": "2019-01-31T19:52:45.472Z", "timezone": "UTC" }, "updatedBy": "cecsusername", "updatedDate": { "value": "2019-02-01T17:49:43.854Z", "timezone": "UTC" }, "categoryProperties": { "links": [ { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950/categoryProperties", "rel": "self", "method": "GET", "mediaType": "application/json" } ] }, "links": [ { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=categoryProperties", "rel": "self", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/taxonomies/5D5AF080B7824C49950443A7D51DE950?fields=categoryProperties", "rel": "canonical", "method": "GET", "mediaType": "application/json" }, { "href": "https://<hostname>/content/management/api/v1.1/metadata-catalog/taxonomies/5D5AF080B7824C49950443A7D51DE950", "rel": "describedby", "method": "GET", "mediaType": "application/schema+json" } ] }