Label
Label
A label groups related content types in a stack, so you can find the content types that work together. Use this class to
- list every label in the stack
- fetch, create, update, or delete one label
- scope label requests to a branch
The label method on Stack returns a new Label. It has two forms:
| Name | Type | Description |
|---|---|---|
| labelUid | String | UID of the label. Omit it to work on all labels. |
Additional Resource The Labels section of the Content Management API (CMA) reference describes every label request and its response.
addBranch
addBranch sets the branch header, so every request from this label object works on that branch.
| Name | Type | Description |
|---|---|---|
| value (required) | String | UID or alias of the branch to work on. |
Returns: Label. The same label, for chaining.
Validation
- There is no client-side validation. addBranch stores any value.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
- A null value passes here. execute() then throws IllegalArgumentException on the next request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addBranch stores the branch header on this label object and makes no request.
- addBranch("<BRANCH>") has the same effect as addHeader("branch", "<BRANCH>"). It replaces a branch header that the stack set with client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "<BRANCH>").
- The header applies to every request method on this object. The stack and other objects keep their own branch header.
Example
Basic usage: list the labels of one branch
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListBranchLabels {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label()
.addBranch("<BRANCH>");
Response<ResponseBody> response = label.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());
}
}addHeader
addHeader adds one request header to the requests that this label object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the request header. |
| value (required) | String | Value of the request header. |
Returns: Label. The same label, for chaining.
Validation
- There is no client-side validation. addHeader stores any key and value.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
- A null key or value passes here. execute() then throws IllegalArgumentException on the next request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addHeader stores the header on this label object and makes no request.
- Every request method on this label object sends every stored header.
- stack.label() copies the stack's headers into the new object. addHeader changes only this object, not the stack or other objects.
- A second call with the same key replaces the first value, including a header the stack set, such as authorization or branch.
Example
Basic usage: fetch a label from another branch
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchLabelOnBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label("<LABEL_UID>")
.addHeader("branch", "<BRANCH>");
Response<ResponseBody> response = label.fetch().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 several request headers at once to the requests that this label object sends.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names and values to add. |
Returns: Label. The same label, for chaining.
Validation
- Throws NullPointerException when the map is null, because addHeaders copies its entries.
- 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 every pair into the headers of this label object and makes no request.
- Every request method on this label object sends every stored header.
- A key that already exists takes the new value, including a header the stack set, such as authorization or branch.
Example
Basic usage: add headers from a map
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class ListLabelsWithHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, String> headers = new HashMap<>();
headers.put("branch", "<BRANCH>");
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label().addHeaders(headers);
Response<ResponseBody> response = label.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 the requests that this label object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | Object | Value of the query parameter. |
Returns: Label. The same label, for chaining.
Validation
- There is no client-side validation. addParam stores any key and value.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
- A null key or value passes here. execute() then throws IllegalArgumentException on a request that sends query parameters.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. addParam stores the pair on this label object and makes no request.
- find and fetch send every stored parameter. create, update, and delete do not send them.
- The SDK writes the value with its toString() method. Pass a JSONObject for a JSON value such as query, because its toString() returns JSON.
- A second call with the same key replaces the first value. The parameter stays on the object for every later request until removeParam removes it.
Example
Basic usage: include the total count when you list labels
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class CountLabels {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label()
.addParam("include_count", true);
Response<ResponseBody> response = label.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 several query parameters at once to the requests that this label object sends.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Query parameter names and values to add. |
Returns: Label. The same label, for chaining.
Validation
- Throws NullPointerException when the map is null, because addParams copies its entries.
- 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 every pair into the query parameters of this label object and makes no request.
- find and fetch send every stored parameter. create, update, and delete do not send them.
- A key that already exists takes the new value. Keys that are not in the map keep their values.
Example
Basic usage: add a count and branch details in one call
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class ListLabelsWithParams {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, Object> params = new HashMap<>();
params.put("include_count", true);
params.put("include_branch", true);
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label().addParams(params);
Response<ResponseBody> response = label.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 builds the request that creates a label from the details in the request body.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the label under a label key. |
| requestBody.label.name (required) | String | Name of the new label. |
| requestBody.label.parent | List<String> | UIDs of the parent labels. |
| requestBody.label.content_types | List<String> | UIDs of the content types the label groups. |
Returns: Call<ResponseBody>. The request for the new label, sent when you call execute().
Validation
- There is no client-side validation. create does not check requestBody.
- execute() throws IllegalArgumentException when requestBody is null, because the request needs 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
- One execute() sends one Add label request (POST /v3/labels) with requestBody as the JSON body.
- create sends the headers on this object. It does not send the query parameters from addParam.
- The response body is the raw JSON from the API, with the new label under a label key.
Example
Basic usage: create a label with a name only
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateLabel {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label();
JSONObject details = new JSONObject();
details.put("name", "docs-test-blog-labels");
JSONObject requestBody = new JSONObject();
requestBody.put("label", details);
Response<ResponseBody> response = label.create(requestBody).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());
}
}All parameters: create a child label that groups two content types
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateChildLabel {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label();
JSONArray parent = new JSONArray();
parent.add("<LABEL_UID>");
JSONArray contentTypes = new JSONArray();
contentTypes.add("<CONTENT_TYPE_UID>");
contentTypes.add("author");
JSONObject details = new JSONObject();
details.put("name", "docs-test-news-labels");
details.put("parent", parent);
details.put("content_types", contentTypes);
JSONObject requestBody = new JSONObject();
requestBody.put("label", details);
Response<ResponseBody> response = label.create(requestBody).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}delete
delete builds the request that deletes one label from the stack.
Returns: Call<ResponseBody>. The request for the deletion notice, sent when you call execute().
Validation
- Throws IllegalAccessError when the label has no UID or an empty UID, because the request path needs one. Create the object with stack.label("<LABEL_UID>").
- 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
Warning delete removes the label from the stack. The Labels API has no request that restores a deleted label, so create it again with create if you need it back.
- One execute() sends one Delete label request (DELETE /v3/labels/{label_uid}).
- delete sends the headers on this object. It does not send the query parameters from addParam.
- The response body is the raw JSON from the API, with a notice message.
Example
Basic usage: delete a label
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteLabel {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label("<LABEL_UID>");
Response<ResponseBody> response = label.delete().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: catch the error for a label without a UID
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
public class DeleteLabelWithoutUid {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label();
try {
label.delete();
} catch (IllegalAccessError error) {
// Fires before any request, because stack.label() holds no label UID
System.out.println("Pass the label UID to stack.label(): " + error.getMessage());
}
}
}fetch
fetch builds the request that retrieves one label by its UID.
Returns: Call<ResponseBody>. The request for the label, sent when you call execute().
Validation
- Throws IllegalAccessError when the label has no UID or an empty UID, because the request path needs one. Create the object with stack.label("<LABEL_UID>").
- 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
- One execute() sends one Get a single label request (GET /v3/labels/{label_uid}) with the headers and query parameters on this object.
- The API reference lists include_branch for this request. Add it with addParam to include the _branch key in the response.
- The response body is the raw JSON from the API, with the label under a label key.
Example
Basic usage: fetch one label
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchLabel {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label("<LABEL_UID>");
Response<ResponseBody> response = label.fetch().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());
}
}Branch details: fetch a label from a branch and include the branch key
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchLabelFromBranch {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "<BRANCH>")
.label("<LABEL_UID>")
.addParam("include_branch", true);
Response<ResponseBody> response = label.fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}find
find builds the request that lists every label in the stack.
Returns: Call<ResponseBody>. The request for the stack's labels, 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
- One execute() sends one Get all labels request (GET /v3/labels) with the headers and query parameters on this object.
- The API reference lists the following three query parameters for this request. Add them with addParam before you call find:
- include_count: true adds the total number of labels to the response.
- query: a JSON query that filters the labels.
- include_branch: true adds the _branch key to the response.
- The response body is the raw JSON from the API, with the labels under a labels array. Read it once with response.body().string().
- The SDK sends one request and does not page through results.
Example
Basic usage: list every label in the stack
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListLabels {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label();
Response<ResponseBody> response = label.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());
}
}Filter and count: list the labels with a given name and include the total
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class FindLabelsByName {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
JSONObject query = new JSONObject();
query.put("name", "Blog");
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label()
.addParam("query", query)
.addParam("include_count", true);
Response<ResponseBody> response = label.find().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}removeParam
removeParam removes one query parameter from this label object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter to remove. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. A key that the object does not hold changes nothing, and removeParam does not throw.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. removeParam deletes the parameter from this label object and makes no request.
- Later requests from find and fetch no longer send the parameter.
- removeParam returns nothing, so call it as its own statement, not in a chain.
Example
Basic usage: drop a parameter before the next request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveLabelParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label()
.addParam("include_count", true)
.addParam("include_branch", true);
label.removeParam("include_branch");
Response<ResponseBody> response = label.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());
}
}update
update builds the request that changes the name, parent labels, or content types of one label.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Request body with the label under a label key. |
| body.label.name | String | New name of the label. |
| body.label.parent | List<String> | UIDs of the parent labels. |
| body.label.content_types | List<String> | UIDs of the content types the label groups. |
Returns: Call<ResponseBody>. The request for the updated label, sent when you call execute().
Validation
- Throws IllegalAccessError when the label has no UID or an empty UID, because the request path needs one. Create the object with stack.label("<LABEL_UID>").
- execute() throws IllegalArgumentException when body is null, because the request needs 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
- One execute() sends one Update label request (PUT /v3/labels/{label_uid}) with body as the JSON body.
- update sends the headers on this object. It does not send the query parameters from addParam.
- The response body is the raw JSON from the API, with the updated label under a label key.
Example
Basic usage: rename a label
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class RenameLabel {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label("<LABEL_UID>");
JSONObject details = new JSONObject();
details.put("name", "Blog");
JSONObject body = new JSONObject();
body.put("label", details);
Response<ResponseBody> response = label.update(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());
}
}All parameters: rename a label, move it under a parent, and change its content types
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Label;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateLabelDetails {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Label label = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").label("<LABEL_UID>");
// Pass the UID of the parent label as the first program argument
JSONArray parent = new JSONArray();
parent.add(args[0]);
JSONArray contentTypes = new JSONArray();
contentTypes.add("<CONTENT_TYPE_UID>");
JSONObject details = new JSONObject();
details.put("name", "Blog");
details.put("parent", parent);
details.put("content_types", contentTypes);
JSONObject body = new JSONObject();
body.put("label", details);
Response<ResponseBody> response = label.update(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}