Taxonomies operations

Overview

Classifications are used to organize content in your website. You can apply them to all Sitefinity CMS content items.

In Sitefinity CMS, there are two types of taxonomies:

  • Flat
  • Hierarchical

For each type there is a build-in classification in the CMS – Tags(flat) and Categories(hierarchical). You can also create custom taxonomies to fit your business needs.

Terminology

  • Taxonomy
    A taxonomy is a classification, it can be flat or hierarchical, or built-in or custom.
    For example, Categories is a built-in hierarchical taxonomy.
  • Taxon
    A taxon is an item or a group of items, which the taxonomist identifies as a separate unit. Taxa is the plural for taxon. A taxonomy contains multiple taxa.
    For example, Sports and Business can be two taxa from the Categories taxonomy, applied to news items.
  • TaxonName This is the single item name for all taxa in the taxonomy.
    For example, in the custom taxonomy Press releases, the single item name for the taxa can be Press release.

Create a taxonomy

To create a taxonomy, you must execute a POST request to the following endpoint:

{baseurl}/api/default/taxonomies

Sample request

POST http://mysite.com/api/default/taxonomies

NOTE: The Type property controls whether the created taxonomy should be flat or hierarchical:
  • 0 – creates a flat taxonomy
  • 1 – creates a hierarchical taxonomy

Sample response

Get a collection of taxonomies

To get all classifications, you must execute a GET request to the following endpoint:

{baseurl}/api/default/taxonomies

Sample request

GET http://mysite.com/api/default/taxonomies

Sample response

NOTE: The request returns both flat and hierarchical taxonomies.

Create a taxon

To create a taxon, you must execute a POST request to the following endpoint:

{baseurl}/api/default/{taxaUrl}

Where {taxaUrl} is one of the following:

  • flat-taxa – for creating a flat taxon
  • hierarchy-taxa – for creating a hierarchical taxon

Sample request

POST http://mysite.com/api/default/flat-taxa

TaxonomyId is the ID of the taxonomy under which the taxon will be created. For example, the ID of Tags taxonomy.

NOTE : If you are creating a taxon, you must add the ParentId property to the body of the request. The ParientId is the ID of the taxon, under which the current taxon must be added. For example, if you want to add Tennis under Sports, you must include the ID of Sports taxon. If you want to add the taxon on root level of the taxonomy, set the ParentId value to 00000000-0000-0000-0000-000000000000.

Sample response

Get a collection of taxa

To get all flat or all hierarchical taxa, you must execute a GET request to the following endpoint:

{baseurl}/api/default/{taxaUrl}

Where {taxaUrl} is one of the following:

  • flat-taxa – for getting all flat taxa
  • hierarchy-taxa – for getting all hierarchical taxa

Sample request

GET http://mysite.com/api/default/flat-taxa

Sample response

Set taxon to a content item

Once you have created taxonomies and taxa, you can start relating them to content items.

To apply a taxon to a content item, execute a PATCH request to the following endpoint:

{baseurl}/api/default/{entity}({itemId})

Where:

  • {entity} is the entity of the module that the item belongs to
  • {itemId} is the ID of the item

In the request body, you must pass the name of the taxonomy (built-in or custom), which the taxon you want to apply belongs to, and the ID of the taxon that you want to set to the content item.

Sample request

PATCH http://mysite.com/api/default/newsitems(3b177186-8b09-497c-8def-58613183d670)

NOTE : The value of the taxon ID property is an array and you can pass multiple taxon IDs.

Sample response

No response body

Want to learn more?

Sign up for our free beginner training. Boost your credentials through advanced courses and certification.
Register for Sitefinity training and certification.

Was this article helpful?

Next article

Special endpoints