Term

AddParam adds one query parameter to the term requests.

Returns: Term. The same term, for chaining.

Validation

• Throws ArgumentNullException if key is null, because the SDK stores parameters in a dictionary keyed by name.
• There is no other client-side validation. A null value sends the parameter with an empty value.
• An invalid value surfaces as a ContentstackException (or a subclass) when Fetch, Ancestors or Descendants sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Client-side only. AddParam stores the pair and makes no request. A second call with the same key replaces the first value, including a value from SetLocale or Depth.
• Fetch, Ancestors and Descendants send the value. Locales does not.
• Use it for the parameters this class has no method for, for example skip and limit. They page the results of Ancestors and Descendants (Get descendants of a term).

Example

Basic usage: page through the descendants of a term

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonArray descendants = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .AddParam("skip", "20")
        .AddParam("limit", "20")
        .Descendants<JsonArray>();
    Console.WriteLine($"Descendants on this page: {descendants.Count}");
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

Ancestors retrieves the terms above this one in the taxonomy hierarchy, up to the root.

Returns: Task<T>. The ancestor terms of the term.

Validation

• There is no client-side validation.
• Throws TaxonomyException if the request fails, for example for an unknown taxonomy UID or term UID.
• Throws TaxonomyException with ErrorCode 0 if the response does not deserialize into T. A T that holds a single object, for example a model class, fails this way, because the SDK reads an array.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Calls GET /taxonomies/{taxonomy_uid}/terms/{term_uid}/ancestors (Get ancestors of a term) and makes one HTTP request per call.
• Deserializes the terms array of the response into T and returns it.
• Sends every query parameter stored on the instance, from SetLocale, IncludeFallback, Depth, IncludeBranch and AddParam.
• Returns the ancestors in the locale the term resolves to. When the term falls back to another locale, its ancestors come back in that locale too.
• Does not return the term itself. Use the Fetch method to read it.

Limitations

• Does not filter entries. To match entries tagged with a term or its ancestors, use the EqualAndAbove method on a Taxonomy.

Example

Basic usage: list the ancestors of a term

using System;
using System.Collections.Generic;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    List<TermInfo> ancestors = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .Ancestors<List<TermInfo>>();
    foreach (TermInfo ancestor in ancestors)
    {
        Console.WriteLine($"{ancestor.Uid}: {ancestor.Name}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}

Localized: list the ancestors in a locale, with fallback

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonArray ancestors = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .SetLocale("<LOCALE>")
        .IncludeFallback()
        .Ancestors<JsonArray>();
    foreach (JsonNode ancestor in ancestors)
    {
        Console.WriteLine($"{ancestor["name"]} ({ancestor["locale"]})");
    }
}
catch (ContentstackException e)
{
    Console.WriteLine(e.Message);
}

Depth sets the depth of the term hierarchy that the term requests retrieve.

Returns: Term. The same term, for chaining.

Validation

• There is no client-side validation. Depth stores zero or a negative number as given.
• An invalid value surfaces as a ContentstackException (or a subclass) when Fetch, Ancestors or Descendants sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Client-side only. Depth stores the depth query parameter and makes no request. A second call replaces the first value.
• Fetch, Ancestors and Descendants send the value. Locales does not.
• Without Depth, the SDK sends no depth value and the API applies its own (Get descendants of a term).
• The value persists on the instance, so a depth you set for Descendants also reaches a later Fetch or Ancestors call on the same Term.

Example

Basic usage: list two levels of descendants

using System;
using System.Collections.Generic;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    List<TermInfo> descendants = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .Depth(2)
        .Descendants<List<TermInfo>>();
    foreach (TermInfo descendant in descendants)
    {
        Console.WriteLine($"{descendant.Uid}: {descendant.Name}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}

Descendants retrieves the terms below this one in the taxonomy hierarchy.

Returns: Task<T>. The descendant terms of the term.

Validation

• There is no client-side validation.
• Throws TaxonomyException if the request fails, for example for an unknown taxonomy UID or term UID.
• Throws TaxonomyException with ErrorCode 0 if the response does not deserialize into T. A T that holds a single object, for example a model class, fails this way, because the SDK reads an array.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Calls GET /taxonomies/{taxonomy_uid}/terms/{term_uid}/descendants (Get descendants of a term) and makes one HTTP request per call.
• Deserializes the terms array of the response into T and returns it.
• Sends every query parameter stored on the instance, from SetLocale, IncludeFallback, Depth, IncludeBranch and AddParam.
• Chain Depth to set the depth of the hierarchy the API retrieves. Without it, the SDK sends no depth value and the API applies its own.
• With IncludeFallback, the API also returns the descendants that have no localization in the requested locale, through the locale fallback hierarchy of the branch.
• Does not page automatically. Send skip and limit through AddParam to page through a large set.

Limitations

• Does not filter entries. To match entries tagged with a term or its descendants, use the EqualAndBelow method on a Taxonomy.

Example

Basic usage: list the descendants of a term

using System;
using System.Collections.Generic;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    List<TermInfo> descendants = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .Descendants<List<TermInfo>>();
    foreach (TermInfo descendant in descendants)
    {
        Console.WriteLine($"{descendant.Uid}: {descendant.Name}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}

Depth and paging: list two levels of descendants, 20 at a time

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonArray descendants = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .Depth(2)
        .AddParam("skip", "0")
        .AddParam("limit", "20")
        .Descendants<JsonArray>();
    Console.WriteLine($"Descendants on this page: {descendants.Count}");
}
catch (ContentstackException e)
{
    Console.WriteLine(e.Message);
}

Fetch reads one published term by its UID.

Returns: Task<T>. The requested term.

Validation

• There is no client-side validation. The Term method already rejected a null or empty term UID.
• Throws TaxonomyException if the request fails, for example for an unknown taxonomy UID or term UID.
• Throws TaxonomyException with ErrorCode 0 if the response does not deserialize into T.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Calls GET /taxonomies/{taxonomy_uid}/terms/{term_uid} (Get a single term) and makes one HTTP request per call.
• Deserializes the term object of the response into T and returns it.
• Sends every query parameter stored on the instance, from SetLocale, IncludeFallback, Depth, IncludeBranch and AddParam.
• With a locale and no fallback, the API returns a 404 error for a term that has no localization in that locale. Chain IncludeFallback to receive the term through the locale fallback hierarchy of the branch.
• Does not return the ancestors or descendants of the term. Use the Ancestors or Descendants method.

Example

Basic usage: read a term into a model class

using System;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    TermInfo term = await client.Taxonomies("<TAXONOMY_UID>").Term("<TERM_UID>").Fetch<TermInfo>();
    Console.WriteLine($"{term.Uid}: {term.Name}");
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}

Localized: read a term in a locale, with fallback

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonObject term = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .SetLocale("<LOCALE>")
        .IncludeFallback()
        .Fetch<JsonObject>();
    Console.WriteLine($"{term["name"]} ({term["locale"]})");
}
catch (ContentstackException e)
{
    Console.WriteLine(e.Message);
}

IncludeBranch requests the branch information of the term by sending include_branch=true.

Returns: Term. The same term, for chaining.

Validation

• There is no client-side validation.
• An invalid value surfaces as a ContentstackException (or a subclass) when Fetch, Ancestors or Descendants sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Client-side only. IncludeBranch stores include_branch=true and makes no request. No method removes it, so build a new instance to send a request without it.
• Fetch, Ancestors and Descendants send the value. Locales does not.
• Does not choose the branch. The Branch option on ContentstackOptions sets the branch the SDK reads from.

Example

Basic usage: read a term with its branch information

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonObject term = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .IncludeBranch()
        .Fetch<JsonObject>();
    Console.WriteLine(term["_branch"]);
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

IncludeFallback returns terms through the locale fallback hierarchy of the branch when they have no localization in the requested locale.

Returns: Term. The same term, for chaining.

Validation

• There is no client-side validation.
• An invalid value surfaces as a ContentstackException (or a subclass) when Fetch, Ancestors or Descendants sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Client-side only. IncludeFallback stores include_fallback=true and makes no request. No method removes it, so build a new instance to send a request without it.
• Fetch, Ancestors and Descendants send the value. Locales does not.
• The API applies it per request:
  • On Fetch, a term with no localization in the requested locale returns through the fallback hierarchy instead of a 404 error (Get a single term).
  • On Ancestors, the term and its ancestors return through the fallback hierarchy (Get ancestors of a term).
  • On Descendants, the response also includes the descendants that have no localization in the requested locale (Get descendants of a term).
• Works with or without SetLocale.
• To use the fallback hierarchy of a branch other than main, set Branch on ContentstackOptions, so the SDK sends the branch header.

Example

Basic usage: read a term with locale fallback

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonObject term = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .SetLocale("<LOCALE>")
        .IncludeFallback()
        .Fetch<JsonObject>();
    Console.WriteLine($"{term["name"]} ({term["locale"]})");
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

Locales lists every published localized version of the term.

Returns: Task<T>. The localized versions of the term.

Validation

• There is no client-side validation.
• Throws TaxonomyException if the request fails, for example for an unknown taxonomy UID.
• Throws TaxonomyException with ErrorCode 0 if the response does not deserialize into T. A T that holds a single object, for example a model class, fails this way, because the SDK reads an array.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Calls GET /taxonomies/{taxonomy_uid}/terms/{term_uid}/locales (Get a single term in all locales) and makes one HTTP request per call.
• Deserializes the terms array of the response into T and returns it. Each item is one localized version of the term.
• Sends only the environment. The query parameters stored on the instance, for example from SetLocale or AddParam, do not reach this request.
• Returns every localized version, whatever locale you set.

Example

Basic usage: list the localized versions of a term

using System;
using System.Collections.Generic;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    List<TermInfo> versions = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .Locales<List<TermInfo>>();
    foreach (TermInfo version in versions)
    {
        Console.WriteLine($"{version.Locale}: {version.Name}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
    public string Locale { get; set; }
}

SetLocale sets the locale that the term requests return the term names in.

Returns: Term. The same term, for chaining.

Validation

• There is no client-side validation of the locale code.
• A null or empty locale changes nothing. SetLocale keeps any locale set earlier and does not throw.
• An invalid value surfaces as a ContentstackException (or a subclass) when Fetch, Ancestors or Descendants sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

• Client-side only. SetLocale stores the locale query parameter and makes no request. A second call replaces the first value.
• Fetch, Ancestors and Descendants send the value. Locales does not.
• Without IncludeFallback, Fetch returns a 404 error for a term that has no localization in this locale (Get a single term).
• A locale set on the Taxonomy does not reach the term. Set it on the Term itself.

Example

Basic usage: read a term in a locale

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonObject term = await client.Taxonomies("<TAXONOMY_UID>")
        .Term("<TERM_UID>")
        .SetLocale("<LOCALE>")
        .Fetch<JsonObject>();
    Console.WriteLine(term["name"]);
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}