Taxonomy

View as Markdown

Taxonomy

A taxonomy arranges the content of a stack into a hierarchy of terms. The Taxonomy class builds the Content Management API requests that manage the taxonomies of one stack. Use this class to

  • list, read, create, update and delete taxonomies
  • add or remove the localized values of one taxonomy
  • publish or unpublish taxonomies to environments and locales
  • reach the terms of one taxonomy through the Terms class

Call the taxonomy method of the Stack class to get an instance.

addHeader

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

NameTypeDescription
key (required)String

Names the header.

Default: Not applicable
value (required)String

Sets the header value.

Default: Not applicable

Returns: Taxonomy. The same taxonomy, 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 Taxonomy 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 reaches this object and every Terms object that terms returned from it, because they share one header map. The stack keeps its own headers.

Example

Basic usage: send the branch header with each request

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

import java.io.IOException;

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

        Response<ResponseBody> response = taxonomy.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 Taxonomy object builds.

NameTypeDescription
headers (required)HashMap<String, String>

Maps each header name to its value.

Default: Not applicable

Returns: Taxonomy. The same taxonomy, 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 Taxonomy sends the headers.
  • The header reaches this object and every Terms object that terms returned from it, because they share one header map. The stack keeps its own headers.
  • 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.Taxonomy;
import okhttp3.ResponseBody;
import retrofit2.Response;

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

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

        Response<ResponseBody> response = taxonomy.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 Taxonomy 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: Taxonomy. The same taxonomy, 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, localize and unlocalize.
  • create, update, delete, publish, unpublish and query 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. Taxonomy 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 calls to find and fetch on this object send that locale.

Example

Basic usage: include the term count of each taxonomy

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

import java.io.IOException;

public class AddTaxonomyParam {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Taxonomy taxonomy = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy();
        taxonomy.addParam("include_terms_count", true);

        Response<ResponseBody> response = taxonomy.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 Taxonomy object.

NameTypeDescription
params (required)HashMap<String, Object>

Maps each query parameter name to its value.

Default: Not applicable

Returns: Taxonomy. The same taxonomy, 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, localize and unlocalize.
  • The addParam method adds one parameter at a time.

Example

Basic usage: list taxonomies with counts and a page size

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

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

public class AddTaxonomyParams {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Taxonomy taxonomy = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy();
        HashMap<String, Object> query = new HashMap<>();
        query.put("include_terms_count", true);
        query.put("include_count", true);
        query.put("limit", 10);
        taxonomy.addParams(query);

        Response<ResponseBody> response = taxonomy.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());
    }
}

create

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

NameTypeDescription
body (required)JSONObject

Holds the taxonomy details under a taxonomy key.

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

Sets the UID of the new taxonomy.

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

Names the taxonomy.

Default: Not applicable
body.taxonomy.descriptionString

Describes the taxonomy.

Default: API default

Returns: Call<ResponseBody>. The request that creates the taxonomy, 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.
  • 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 with the body as JSON, as Create a taxonomy describes.
  • Choose a UID outside the restricted keywords for UIDs that the API reference lists.
  • Sends no query parameters, so the API creates the taxonomy in the master locale.
  • create ignores the UID of the instance.

Example

Basic usage: create a taxonomy

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

import java.io.IOException;

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

        JSONObject details = new JSONObject();
        details.put("uid", "docs_test_color");
        details.put("name", "docs-test-color");
        details.put("description", "Colors that products come in");
        JSONObject body = new JSONObject();
        body.put("taxonomy", details);

        Response<ResponseBody> response = taxonomy.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());
    }
}

delete

delete builds the request that deletes the taxonomy whose UID you pass, together with all its terms.

NameTypeDescription
taxonomyId (required)String

Identifies the taxonomy to delete.

Default: Not applicable

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

Validation

  • There is no client-side validation of taxonomyId.
  • A null UID makes execute() throw 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 DELETE /v3/taxonomies/{taxonomy_uid}, as Delete a taxonomy describes.
  • Values from addParam do not reach this request.
  • delete uses its argument, not the UID of the instance.

Example

Basic usage: request the deletion of a taxonomy and check the result

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

import java.io.IOException;

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

        Response<ResponseBody> response = taxonomy.delete("<TAXONOMY_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("Deleted, status " + response.code());
    }
}

fetch

fetch retrieves one taxonomy by the UID that you pass.

NameTypeDescription
taxonomyId (required)String

Identifies the taxonomy to read.

Default: Not applicable

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

Validation

  • There is no client-side validation of taxonomyId.
  • A null UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • An empty UID does not throw. fetch then sends GET /v3/taxonomies/, which names no taxonomy.
  • 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} with every query parameter stored on this object, as Get a single taxonomy describes.
  • The API accepts locale, include_fallback, include_terms_count, include_referenced_terms_count and include_referenced_entries_count on this request. Add them with addParam.
  • Without a locale parameter, the API returns the taxonomy in the master locale.
  • fetch uses its argument, not the UID of the instance, so it works on stack.taxonomy() too.

Example

Basic usage: read one taxonomy

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

import java.io.IOException;

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

        Response<ResponseBody> response = taxonomy.fetch("<TAXONOMY_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 localized taxonomy with its term counts

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

import java.io.IOException;

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

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

find

find lists the taxonomies of the stack, with the query parameters that you add to this object.

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

Validation

  • There is no client-side validation.
  • 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 with every query parameter stored on this object, as Get all taxonomies describes.
  • Add query parameters with addParam or addParams before you call find. The API accepts the following parameters:
    • locale and include_fallback: read the taxonomies in a locale, with or without the fallback hierarchy.
    • include_terms_count, include_referenced_terms_count, include_referenced_entries_count and include_count: add counts to the response.
    • deleted: set to true to list only deleted taxonomies.
    • asc, desc, query and typeahead: sort and filter the list.
    • 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 find too.
  • find ignores the UID of the instance. The response body is the raw JSON of the API, with the taxonomies in its taxonomies array.

Example

Basic usage: list the taxonomies of a stack

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

import java.io.IOException;

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

        Response<ResponseBody> response = taxonomy.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: read the second page of ten, with term counts

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

import java.io.IOException;

public class FindTaxonomiesPage {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Taxonomy taxonomy = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy()
                .addParam("include_terms_count", true)
                .addParam("include_count", true)
                .addParam("limit", 10)
                .addParam("skip", 10);

        Response<ResponseBody> response = taxonomy.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 this taxonomy in one locale.

NameTypeDescription
body (required)JSONObject

Holds the translated values under a taxonomy key.

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

Sets the name in the target locale.

Default: Not applicable
body.taxonomy.descriptionString

Sets the description in the target locale.

Default: API default
locale (required)String

Names the target locale code.

Default: Not applicable

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

Validation

  • Throws NullPointerException if the instance has no taxonomy UID, because localize changes one taxonomy. Get the instance with stack.taxonomy(taxonomyUid).
  • There is no client-side validation of body or locale. A null body makes execute() throw IllegalArgumentException, and so does a null locale.
  • 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}?locale={locale} with the body as JSON, as Localize a taxonomy 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 calls to find, fetch and unlocalize on the same object 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 name and description

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

import java.io.IOException;

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

        // The values in the target locale
        JSONObject details = new JSONObject();
        details.put("name", "Farbe");
        details.put("description", "Farben der Produkte");
        JSONObject body = new JSONObject();
        body.put("taxonomy", details);

        Response<ResponseBody> response = taxonomy.localize(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());
    }
}

Edge case: call localize on an instance without a UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Taxonomy;
import org.json.simple.JSONObject;

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

        try {
            taxonomy.localize(new JSONObject(), "<LOCALE>");
        } catch (NullPointerException e) {
            // Thrown before any request, because the instance holds no taxonomy UID
            System.out.println("No taxonomy UID: " + e.getMessage());
        }
    }
}

publish

publish starts a job that publishes one or more taxonomies, with all their terms, to the environments and locales in the request body.

NameTypeDescription
body (required)JSONObject

Names the taxonomies, environments and locales.

Default: Not applicable
body.locales (required)Array

Lists the locale codes to publish to.

Default: Not applicable
body.environments (required)Array

Lists the environment names to publish to.

Default: Not applicable
body.items (required)Array

Lists the taxonomies, each as an object with a uid.

Default: Not applicable

Returns: Call<ResponseBody>. The request that starts the publish job, sent when you call execute().

Validation

  • There is no client-side validation. publish sends the body unchanged.
  • A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a 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 POST /v3/taxonomies/publish with the body as JSON, as Publish a taxonomy describes.
  • The API requires the api_version header on this request, and the SDK does not set it. Add it with addHeader first. The header then stays on this object for every later request.
  • The API handles a taxonomy as a whole. It queues the taxonomy definition and every term in it together, so items lists taxonomies, not terms.
  • The response carries a job ID. The API runs the job in the background, so track its outcome in the publish queue of the stack.
  • A branch header, from the stack or from addHeader, sets the branch whose locale fallback hierarchy the job applies. Without it, the API uses the main branch.
  • Sends no query parameters. publish ignores the UID of the instance.

Example

Basic usage: publish one taxonomy in one environment and locale

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

import java.io.IOException;

public class PublishTaxonomy {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Taxonomy taxonomy = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy()
                .addHeader("api_version", "3.2");

        JSONArray locales = new JSONArray();
        locales.add("<LOCALE>");
        JSONArray environments = new JSONArray();
        environments.add("<ENVIRONMENT>");
        JSONObject item = new JSONObject();
        item.put("uid", "<TAXONOMY_UID>");
        JSONArray items = new JSONArray();
        items.add(item);

        JSONObject body = new JSONObject();
        body.put("locales", locales);
        body.put("environments", environments);
        body.put("items", items);

        Response<ResponseBody> response = taxonomy.publish(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;
        }
        // The body holds the job ID. Track the job in the publish queue.
        System.out.println(response.body().string());
    }
}

query

query builds a request for the entries whose taxonomy fields match the conditions that you pass.

NameTypeDescription
query (required)JSONObject

Holds the taxonomy conditions under their field paths.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the entries that match the taxonomy query, sent when you call execute().

Validation

  • There is no client-side validation. query sends the object unchanged.
  • A null query does not throw. The request then goes out without a query parameter.
  • 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/entries with the JSON text of the object as the query parameter.
  • The Content Management API reference does not document a request at this path. The Content Delivery API documents the same path as Get all entries with defined taxonomies, with the condition shapes it accepts.
  • Sends the headers of this object, and no other query parameter. Values from addParam do not reach this request.
  • query ignores the UID of the instance.

Example

Basic usage: find entries tagged with either of two terms

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

import java.io.IOException;

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

        JSONArray terms = new JSONArray();
        terms.add("red");
        terms.add("yellow");
        JSONObject in = new JSONObject();
        in.put("$in", terms);
        JSONObject condition = new JSONObject();
        condition.put("taxonomies.color", in);

        Response<ResponseBody> response = taxonomy.query(condition).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());
    }
}

terms

terms returns a Terms object that works with the terms of this taxonomy.

Returns: Terms. A new terms object for this taxonomy.

Validation

  • There is no client-side validation, and terms does not throw.
  • On an instance without a taxonomy UID, the returned object holds no UID. Its requests that name a taxonomy make execute() throw IllegalArgumentException, because Retrofit rejects a null path value. Its search method still works, because it searches across all taxonomies.
  • Errors from the API surface when you call execute() on a request that the returned object builds.

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

Behavior

  • Client-side only. terms builds the object and sends no request.
  • The returned object takes the taxonomy UID of this instance.
  • The returned object shares the header map of this taxonomy. A header that you add to either object reaches the requests of both.
  • The returned object starts with no query parameters of its own. Parameters stored on this taxonomy do not carry over.
  • Each call returns a new object. The Terms class page lists its methods.

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 ListTerms {
    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());
    }
}

unlocalize

unlocalize removes the translated values of this taxonomy in one locale.

NameTypeDescription
locale (required)String

Names the locale code to remove.

Default: Not applicable

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

Validation

  • Throws NullPointerException if the instance has no taxonomy UID, because unlocalize changes one taxonomy. Get the instance with stack.taxonomy(taxonomyUid).
  • There is no client-side validation of locale. A null locale makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map 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 DELETE /v3/taxonomies/{taxonomy_uid}?locale={locale}, as Unlocalize a taxonomy 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 calls to find, fetch and localize on the same object send it too, until a later localize or unlocalize call replaces it.

Example

Basic usage: remove the values of one locale

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

import java.io.IOException;

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

        Response<ResponseBody> response = taxonomy.unlocalize("<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());
    }
}

unpublish

unpublish starts a job that unpublishes one or more taxonomies, with all their terms, from the environments and locales in the request body.

NameTypeDescription
body (required)JSONObject

Names the taxonomies, environments and locales.

Default: Not applicable
body.locales (required)Array

Lists the locale codes to unpublish from.

Default: Not applicable
body.environments (required)Array

Lists the environment names to unpublish from.

Default: Not applicable
body.items (required)Array

Lists the taxonomies, each as an object with a uid.

Default: Not applicable

Returns: Call<ResponseBody>. The request that starts the unpublish job, sent when you call execute().

Validation

  • There is no client-side validation. unpublish sends the body unchanged.
  • A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a 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 POST /v3/taxonomies/unpublish with the body as JSON, as Unpublish a taxonomy describes.
  • The API requires the api_version header on this request, and the SDK does not set it. Add it with addHeader first. The header then stays on this object for every later request.
  • The API handles a taxonomy as a whole. It queues the taxonomy definition and every term in it together, so items lists taxonomies, not terms.
  • The response carries a job ID. The API runs the job in the background, so track its outcome in the publish queue of the stack.
  • A branch header, from the stack or from addHeader, sets the branch whose locale fallback hierarchy the job applies. Without it, the API uses the main branch.
  • Sends no query parameters. unpublish ignores the UID of the instance.

Example

Basic usage: unpublish one taxonomy in one environment and locale

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

import java.io.IOException;

public class UnpublishTaxonomy {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Taxonomy taxonomy = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").taxonomy()
                .addHeader("api_version", "3.2");

        JSONArray locales = new JSONArray();
        locales.add("<LOCALE>");
        JSONArray environments = new JSONArray();
        environments.add("<ENVIRONMENT>");
        JSONObject item = new JSONObject();
        item.put("uid", "<TAXONOMY_UID>");
        JSONArray items = new JSONArray();
        items.add(item);

        JSONObject body = new JSONObject();
        body.put("locales", locales);
        body.put("environments", environments);
        body.put("items", items);

        Response<ResponseBody> response = taxonomy.unpublish(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;
        }
        // The body holds the job ID. Track the job in the publish queue.
        System.out.println(response.body().string());
    }
}

update

update changes the details of the taxonomy whose UID you pass.

NameTypeDescription
taxonomyId (required)String

Identifies the taxonomy to change.

Default: Not applicable
body (required)JSONObject

Holds the new details under a taxonomy key.

Default: Not applicable
body.taxonomy.nameString

Renames the taxonomy.

Default: API default
body.taxonomy.descriptionString

Changes the description.

Default: API default

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

Validation

  • There is no client-side validation.
  • A null UID or body 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} with the body as JSON, as Update a taxonomy describes.
  • Sends no query parameters. The API therefore updates the taxonomy in the master locale, and a locale from addParam does not reach this request.
  • update uses its argument, not the UID of the instance.

Limitations

  • Does not update the values of a non-master locale. Use localize for a locale other than the master locale.

Example

Basic usage: rename a taxonomy

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

import java.io.IOException;

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

        JSONObject details = new JSONObject();
        details.put("name", "docs-test-product-color");
        details.put("description", "Colors for the product catalog");
        JSONObject body = new JSONObject();
        body.put("taxonomy", details);

        Response<ResponseBody> response = taxonomy.update("<TAXONOMY_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());
    }
}