Read a taxonomy

get

/content/management/api/v1.1/taxonomies/{id}

Read a specific taxonomy by id.

Request

Path Parameters
Query Parameters
  • 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
  • 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")
Back to Top

Response

Supported Media Types

200 Response

OK.
Body ()
Root Schema : Taxonomy
Type: object
Taxonomy
Show Source
Nested Schema : availableStates
Type: array
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.
Show Source
Nested Schema : ItemSubResourceListCategoryPropertyDefinition
Type: object
Item SubResource.
Show Source
Nested Schema : date
Type: object
date
Show Source
Nested Schema : customProperties
Type: object
Additional Properties Allowed
Show Source
Custom 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.
Nested Schema : publishedChannels
Type: array
Read Only: true
Taxonomy published channels.
Show Source
Nested Schema : TaxonomyStatus
Type: object
TaxonomyStatus
Show Source
Nested Schema : jobs
Type: array
Show Source
Nested Schema : TaxonomyJobInfo
Type: object
TaxonomyJobInfo
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : CategoryPropertyDefinition
Type: object
Category Property Definition
Show Source
Nested Schema : defaultValues
Type: array
Default values for the property.
Show Source
Nested Schema : PropertySettingsBean
Type: object
Show Source
Nested Schema : PropertySettingsCaasBean
Type: object
Show Source
Nested Schema : customValidators
Type: array
Custom validators for the property value.
Show Source
Nested Schema : PropertySettingsEditorBean
Type: object
Show Source
Nested Schema : PropertySettingsValueCountRangeBean
Type: object
Show Source
Nested Schema : PropertySettingsValidatorBean
Type: object
Show Source
Nested Schema : options
Type: object
Additional Properties Allowed
Show Source
Validator details.
Nested Schema : additionalProperties
Type: object
Nested Schema : options
Type: object
Additional Properties Allowed
Show Source
Options of the property value.
Nested Schema : additionalProperties
Type: object
Nested Schema : ChannelInTaxonomy
Type: object
ChannelInTaxonomy
Show Source

304 Response

Not modified.

400 Response

Bad request.

403 Response

Forbidden.

404 Response

Taxonomy not found. The requested resource not found.

500 Response

Internal server error.
Back to Top

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"
    }
  ]
}
Back to Top