Terms

View as Markdown

Terms

Terms are the entries of a taxonomy hierarchy, and content editors tag entries with them. The Terms class builds the Content Management API requests that manage the terms of one taxonomy. Use this class to

  • list, read, create and update terms
  • read the ancestors or descendants of a term
  • move a term to another parent or position
  • add or remove the localized values of a term
  • search terms across every taxonomy of the stack

Call the terms method of the Taxonomy class on stack.taxonomy(taxonomyUid) to get an instance. The class also has a public constructor, but it takes the internal taxonomy service of the SDK, so use terms() instead.

addHeader

addHeader adds one header to every request that this Terms object builds.

NameTypeDescription
key (required)String

Names the header.

Default: Not applicable
value (required)String

Sets the header value.

Default: Not applicable

Returns: Terms. The same terms object, for chaining.

Validation

  • There is no client-side validation. addHeader stores any name and value.
  • A null name or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addHeader stores the header on this object and sends no request.
  • Every request method of Terms sends the header, together with the headers that the object copied from the stack, such as api_key and authorization.
  • A second call with the same name replaces the value. A name that matches a stack header, such as branch, replaces that header for this object.
  • The header map belongs to the Taxonomy object that created this one. The header therefore also reaches the requests of that taxonomy and of every other Terms object it returned.

Example

Basic usage: send the branch header with each request

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AddTermsHeader {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();
        terms.addHeader("branch", "<BRANCH>");

        Response<ResponseBody> response = terms.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addHeaders

addHeaders adds every entry of a map as a header of the requests that this Terms object builds.

NameTypeDescription
headers (required)HashMap<String, String>

Maps each header name to its value.

Default: Not applicable

Returns: Terms. The same terms object, for chaining.

Validation

  • Throws NullPointerException if the map is null, because addHeaders copies its entries.
  • A null name or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addHeaders copies the entries into the headers of this object and sends no request.
  • A name that already exists takes the new value. Headers that the map does not name stay as they are.
  • Every request method of Terms sends the headers.
  • The header map belongs to the Taxonomy object that created this one. The header therefore also reaches the requests of that taxonomy and of every other Terms object it returned.
  • The addHeader method adds one header at a time.

Example

Basic usage: send the branch header from a map

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class AddTermsHeaders {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();
        HashMap<String, String> headers = new HashMap<>();
        headers.put("branch", "<BRANCH>");
        terms.addHeaders(headers);

        Response<ResponseBody> response = terms.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addParam

addParam adds one query parameter to this Terms object, for the requests that send query parameters.

NameTypeDescription
key (required)String

Names the query parameter.

Default: Not applicable
value (required)Object

Sets the parameter value, sent as its string form.

Default: Not applicable

Returns: Terms. The same terms object, for chaining.

Validation

  • There is no client-side validation. addParam stores any key and value.
  • A null key or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addParam stores the pair on this object and sends no request.
  • Only the following requests send the stored parameters: find, fetch, descendants, ancestors, reorder, localize and unlocalize.
  • create, update and search send no query parameters, so a value you add has no effect on them.
  • Retrofit writes each value with its toString() form, so pass a String, a Boolean or a number.
  • A second call with the same key replaces the value.
  • The parameter stays on this object for every later request. Terms has no public method that removes one, so get a new instance from the stack to start without parameters.
  • localize and unlocalize store their locale argument as a parameter too, so later requests from this object send that locale.
  • Each call to taxonomy.terms() returns a new object with no parameters.

Example

Basic usage: list the terms of a taxonomy to a depth of two levels

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AddTermsParam {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();
        terms.addParam("depth", 2);

        Response<ResponseBody> response = terms.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addParams

addParams adds every entry of a map as a query parameter of this Terms object.

NameTypeDescription
params (required)HashMap<String, Object>

Maps each query parameter name to its value.

Default: Not applicable

Returns: Terms. The same terms object, for chaining.

Validation

  • Throws NullPointerException if the map is null, because addParams copies its entries.
  • A null key or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

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

Behavior

  • Client-side only. addParams copies the entries into the parameters of this object and sends no request.
  • A key that already exists takes the new value. Parameters that the map does not name stay as they are.
  • Only the following requests send the stored parameters: find, fetch, descendants, ancestors, reorder, localize and unlocalize.
  • The addParam method adds one parameter at a time.

Example

Basic usage: list terms with child counts and a total

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class AddTermsParams {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();
        HashMap<String, Object> query = new HashMap<>();
        query.put("depth", 2);
        query.put("include_children_count", true);
        query.put("include_count", true);
        terms.addParams(query);

        Response<ResponseBody> response = terms.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

ancestors

ancestors lists the terms above one term in the taxonomy hierarchy.

NameTypeDescription
termUid (required)String

Identifies the term whose ancestors to list.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the ancestor terms, sent when you call execute().

Validation

  • There is no client-side validation of termUid. A null term UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • On an object whose taxonomy UID is null, execute() throws IllegalArgumentException for the same reason.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends GET /v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/ancestors with every query parameter stored on this object, as Get ancestors of a term describes.
  • Add query parameters with addParam or addParams first. The API accepts the following parameters on this request:
    • locale and include_fallback: read the terms in a locale, with or without the fallback hierarchy.
    • include_children_count, include_referenced_entries_count and include_count: add counts to the response.
    • limit and skip: page through the list. The SDK sets no page size, so the API applies its own.
  • A locale that localize or unlocalize stored on this object goes out with this request too.
  • The response body is the raw JSON of the API, with the terms at the higher levels of the hierarchy.

Example

Basic usage: list the ancestors of a term

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class TermAncestors {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        Response<ResponseBody> response = terms.ancestors("<TERM_UID>").execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Query parameters: list ancestors with counts

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class TermAncestorsWithCounts {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms()
                .addParam("include_children_count", true)
                .addParam("include_count", true);

        Response<ResponseBody> response = terms.ancestors("<TERM_UID>").execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

create

create creates a term in the taxonomy from the details in the request body.

NameTypeDescription
body (required)JSONObject

Holds the term details under a term key.

Default: Not applicable
body.term.uid (required)String

Sets the UID of the new term.

Default: Not applicable
body.term.name (required)String

Names the term.

Default: Not applicable
body.term.parent_uid (required)String

Names the parent term, or null for a root term.

Default: Not applicable
body.term.orderint

Sets the position among terms of the same parent.

Default: API default

Returns: Call<ResponseBody>. The request that creates the term, sent when you call execute().

Validation

  • There is no client-side validation. create sends the body unchanged.
  • A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body. A null taxonomy UID on this object throws the same exception, because Retrofit rejects a null path value.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends POST /v3/taxonomies/{taxonomy_uid}/terms with the body as JSON, as Create a term describes.
  • The SDK drops null values from the body unless you build the client with setSerializeNulls(true). Use that setting to send "parent_uid": null for a root term.
  • Sends no query parameters, so the API creates the term in the master locale.

Example

Basic usage: create a child term under an existing term

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class CreateChildTerm {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        JSONObject term = new JSONObject();
        term.put("uid", "docs_test_navy");
        term.put("name", "docs-test-navy");
        term.put("parent_uid", "<TERM_UID>");
        term.put("order", 1);
        JSONObject body = new JSONObject();
        body.put("term", term);

        Response<ResponseBody> response = terms.create(body).execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Edge case: create a root term, which needs a null parent

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class CreateRootTerm {
    public static void main(String[] args) throws IOException {
        // Without setSerializeNulls(true), the SDK drops "parent_uid": null from the body
        Contentstack client = new Contentstack.Builder().setSerializeNulls(true).build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        JSONObject term = new JSONObject();
        term.put("uid", "docs_test_blue");
        term.put("name", "docs-test-blue");
        term.put("parent_uid", null);
        term.put("order", 1);
        JSONObject body = new JSONObject();
        body.put("term", term);

        Response<ResponseBody> response = terms.create(body).execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

descendants

descendants lists the terms below one term in the taxonomy hierarchy.

NameTypeDescription
termUid (required)String

Identifies the term whose descendants to list.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the descendant terms, sent when you call execute().

Validation

  • There is no client-side validation of termUid. A null term UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • On an object whose taxonomy UID is null, execute() throws IllegalArgumentException for the same reason.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends GET /v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/descendants with every query parameter stored on this object, as Get descendants of a term describes.
  • Add query parameters with addParam or addParams first. The API accepts the following parameters on this request:
    • locale and include_fallback: read the terms in a locale, with or without the fallback hierarchy.
    • depth: limit the number of levels below the term that the response covers.
    • include_children_count, include_referenced_entries_count, include_count and include_order: add counts and term order to the response.
    • limit and skip: page through the list. The SDK sets no page size, so the API applies its own.
  • A locale that localize or unlocalize stored on this object goes out with this request too.
  • The response body is the raw JSON of the API, with the child terms of the term.

Example

Basic usage: list the child terms of a term

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class TermDescendants {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        Response<ResponseBody> response = terms.descendants("<TERM_UID>").execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Query parameters: list two levels of descendants with their order

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class TermDescendantsTwoLevels {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms()
                .addParam("depth", 2)
                .addParam("include_order", true);

        Response<ResponseBody> response = terms.descendants("<TERM_UID>").execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

fetch

fetch retrieves one term of the taxonomy by the UID that you pass.

NameTypeDescription
termUid (required)String

Identifies the term to read.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the term, sent when you call execute().

Validation

  • There is no client-side validation of termUid. A null term UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • On an object whose taxonomy UID is null, execute() throws IllegalArgumentException for the same reason.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends GET /v3/taxonomies/{taxonomy_uid}/terms/{term_uid} with every query parameter stored on this object, as Get a single term describes.
  • Add query parameters with addParam or addParams first. The API accepts the following parameters on this request:
    • locale and include_fallback: read the term in a locale, with or without the fallback hierarchy.
    • include_children_count and include_referenced_entries_count: add counts to the response.
  • A locale that localize or unlocalize stored on this object goes out with this request too.
  • The response body is the raw JSON of the API, with the term under its term key. Without a locale parameter, the API returns the term in the master locale.

Example

Basic usage: read one term

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchTerm {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        Response<ResponseBody> response = terms.fetch("<TERM_UID>").execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Query parameters: read a term in another locale with its child count

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchLocalizedTerm {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms()
                .addParam("locale", "<LOCALE>")
                .addParam("include_fallback", true)
                .addParam("include_children_count", true);

        Response<ResponseBody> response = terms.fetch("<TERM_UID>").execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

find

find lists the terms of the taxonomy, with the query parameters that you add to this object.

Returns: Call<ResponseBody>. The request for the terms of the taxonomy, sent when you call execute().

Validation

  • There is no client-side validation.
  • On an object whose taxonomy UID is null, execute() throws IllegalArgumentException, because Retrofit rejects a null path value.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends GET /v3/taxonomies/{taxonomy_uid}/terms with every query parameter stored on this object, as Get all terms of a taxonomy describes.
  • Add query parameters with addParam or addParams first. The API accepts the following parameters on this request:
    • locale and include_fallback: read the terms in a locale, with or without the fallback hierarchy.
    • depth: return terms from the root level down to this depth.
    • include_children_count, include_referenced_entries_count, include_count and include_order: add counts and term order to the response.
    • asc, desc, query and typeahead: sort and filter the list.
    • deleted: set to true to list only deleted terms.
    • limit and skip: page through the list. The SDK sets no page size, so the API applies its own.
  • A locale that localize or unlocalize stored on this object goes out with this request too.
  • The response body is the raw JSON of the API, with the terms in its terms array.

Example

Basic usage: list the terms of a taxonomy

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FindTerms {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        Response<ResponseBody> response = terms.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Query parameters: list two levels of terms with their order and child counts

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FindTermsTree {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms()
                .addParam("depth", 2)
                .addParam("include_order", true)
                .addParam("include_children_count", true);

        Response<ResponseBody> response = terms.find().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

localize

localize adds the translated values of one term in one locale.

NameTypeDescription
termUid (required)String

Identifies the term to localize.

Default: Not applicable
body (required)JSONObject

Holds the translated values under a term key.

Default: Not applicable
body.term.name (required)String

Sets the name in the target locale.

Default: Not applicable
locale (required)String

Names the target locale code.

Default: Not applicable

Returns: Call<ResponseBody>. The request that adds the localized term, sent when you call execute().

Validation

  • There is no client-side validation.
  • A null term UID, body, locale or taxonomy UID makes execute() throw IllegalArgumentException, because Retrofit rejects null path values, query values and bodies.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends POST /v3/taxonomies/{taxonomy_uid}/terms/{term_uid}?locale={locale} with the body as JSON, as Localize a term describes.
  • Also sends every other query parameter stored on this object.
  • localize stores locale as a query parameter of this object, and it stays there. Later requests from the same object that send query parameters send it too, until a later localize or unlocalize call replaces it.
  • To edit the master locale values, use update.

Example

Basic usage: add a translated term name

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class LocalizeTerm {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        // The name in the target locale
        JSONObject term = new JSONObject();
        term.put("name", "Marineblau");
        JSONObject body = new JSONObject();
        body.put("term", term);

        Response<ResponseBody> response = terms.localize("<TERM_UID>", body, "<LOCALE>").execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

reorder

reorder moves one term to another parent, another position among its siblings, or both.

NameTypeDescription
termUid (required)String

Identifies the term to move.

Default: Not applicable
body (required)JSONObject

Holds the new place under a term key.

Default: Not applicable
body.term.parent_uid (required)String

Names the new parent, or null for the root level.

Default: Not applicable
body.term.order (required)int

Sets the position among siblings, starting at 1.

Default: Not applicable

Returns: Call<ResponseBody>. The request that moves the term, sent when you call execute().

Validation

  • There is no client-side validation.
  • A null term UID, body or taxonomy UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value and a null body.
  • The API rejects a move of a term that has child terms unless the request carries force=true, because the move changes the hierarchy of those children.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends PUT /v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/move with the body as JSON and every query parameter stored on this object, as Move/Reorder a term describes.
  • To move a term with child terms, add force with addParam first. The API defaults force to false. With true, it moves the term and changes the hierarchy of all its child terms.
  • The SDK drops null values from the body unless you build the client with setSerializeNulls(true). Use that setting to send "parent_uid": null for a move to the root level.

Example

Basic usage: move a term to the first position under another parent

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class MoveTerm {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        JSONObject place = new JSONObject();
        place.put("parent_uid", "docs_test_blue");
        place.put("order", 1);
        JSONObject body = new JSONObject();
        body.put("term", place);

        Response<ResponseBody> response = terms.reorder("<TERM_UID>", body).execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Edge case: force-move a term with children to the root level

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class ForceMoveTermToRoot {
    public static void main(String[] args) throws IOException {
        // Without setSerializeNulls(true), the SDK drops "parent_uid": null from the body
        Contentstack client = new Contentstack.Builder().setSerializeNulls(true).build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms()
                .addParam("force", true);

        JSONObject place = new JSONObject();
        place.put("parent_uid", null);
        place.put("order", 2);
        JSONObject body = new JSONObject();
        body.put("term", place);

        Response<ResponseBody> response = terms.reorder("<TERM_UID>", body).execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

search finds the terms whose UID or name matches a string, across every taxonomy of the stack.

NameTypeDescription
termString (required)String

Sets the text to match against term UIDs and names.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the matching terms across all taxonomies, sent when you call execute().

Validation

  • Throws IllegalArgumentException if termString is empty, because the API needs a search string on this request.
  • Throws NullPointerException if termString is null, because search checks its length.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends GET /v3/taxonomies/$all/terms?typeahead={termString}, as Get all terms across all taxonomies describes. $all is the reserved path value for all taxonomies.
  • Sends typeahead only. Values from addParam do not reach this request.
  • Ignores the taxonomy UID of this object, so it works on an object from stack.taxonomy().terms() too.

Limitations

  • Does not send locale, query, limit, skip or the count parameters, which the API accepts on this request.

Example

Basic usage: search all taxonomies for a term

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class SearchTerms {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy().terms();

        Response<ResponseBody> response = terms.search("navy").execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Edge case: an empty search string

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;

public class SearchEmptyString {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy().terms();

        try {
            terms.search("");
        } catch (IllegalArgumentException e) {
            // Thrown before any request, because the search string is empty
            System.out.println("Empty search string: " + e.getMessage());
        }
    }
}

unlocalize

unlocalize removes the translated values of one term in one locale.

NameTypeDescription
termUid (required)String

Identifies the term to change.

Default: Not applicable
locale (required)String

Names the locale code to remove.

Default: Not applicable

Returns: Call<ResponseBody>. The request that removes the localized term, sent when you call execute().

Validation

  • There is no client-side validation.
  • A null term UID, locale or taxonomy UID makes execute() throw IllegalArgumentException, because Retrofit rejects null path and query values.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends DELETE /v3/taxonomies/{taxonomy_uid}/terms/{term_uid}?locale={locale}, as Unlocalize a term describes.
  • Also sends every other query parameter stored on this object.
  • unlocalize stores locale as a query parameter of this object, and it stays there. Later requests from the same object that send query parameters send it too.

Example

Basic usage: remove the values of one locale from a term

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class UnlocalizeTerm {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        Response<ResponseBody> response = terms.unlocalize("<TERM_UID>", "<LOCALE>").execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println("Removed, status " + response.code());
    }
}

update

update changes the details of one term of the taxonomy.

NameTypeDescription
termUid (required)String

Identifies the term to change.

Default: Not applicable
body (required)JSONObject

Holds the new details under a term key.

Default: Not applicable
body.term.nameString

Renames the term.

Default: API default

Returns: Call<ResponseBody>. The request that updates the term, sent when you call execute().

Validation

  • There is no client-side validation.
  • A null term UID, body or taxonomy UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value and a null body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

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

Behavior

  • Sends PUT /v3/taxonomies/{taxonomy_uid}/terms/{term_uid} with the body as JSON, as Update a term describes.
  • Sends no query parameters. The API therefore updates the term in the master locale, and a locale from addParam does not reach this request.
  • To move the term in the hierarchy, use reorder.

Example

Basic usage: rename a term

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Terms;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class UpdateTerm {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Terms terms = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy("<TAXONOMY_UID>").terms();

        JSONObject term = new JSONObject();
        term.put("name", "docs-test-navy-blue");
        JSONObject body = new JSONObject();
        body.put("term", term);

        Response<ResponseBody> response = terms.update("<TERM_UID>", body).execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}