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:
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 taxonhierarchy-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 taxahierarchy-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