Environment
Environment
An Environment manages the publishing environments of one stack. A publishing environment is a deployment destination, such as staging or production, that you publish entries and assets to.
Use this class to
- list every environment of a stack
- fetch the details of one environment
- add an environment with its URLs per language
- update or delete an environment
addHeader
addHeader adds one header to every request of the environment, or replaces the value of an existing one.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header, for example authorization. |
| value (required) | String | Value to send in the header. |
Returns: Environment. The same environment, for chaining.
Validation
- There is no client-side validation.
- 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 in the header map of the environment and sends no request.
- Every request method of the environment sends the map: find, fetch, create, update and delete.
- The environment starts with a copy of the stack's headers. addHeader changes only this environment, not the stack or other objects.
- A second call with the same key replaces the value, including a header copied from the stack, such as api_key or authorization.
Example
Basic usage: send a management token from the environment object
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class EnvironmentAuthorizationHeader {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
// This stack carries only the api_key header
Stack stack = client.stack("<API_KEY>");
Environment environments = stack.environment().addHeader("authorization", "<MANAGEMENT_TOKEN>");
Response<ResponseBody> response = environments.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 several headers to every request of the environment at once.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names and values to add. |
Returns: Environment. The same environment, for chaining.
Validation
- There is no client-side validation.
- 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 entry of headers into the header map of the environment and sends no request.
- An entry replaces a header with the same name, including one copied from the stack. Headers with other names stay.
- Every request method of the environment sends the map. The addHeader method adds one header.
- Later changes to your headers map do not reach the environment, because addHeaders copies the entries.
Example
Basic usage: set the stack credentials on the environment object
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class EnvironmentCredentialHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>");
HashMap<String, String> headers = new HashMap<>();
headers.put("api_key", "<API_KEY>");
headers.put("authorization", "<MANAGEMENT_TOKEN>");
Environment environment = stack.environment("<ENVIRONMENT>").addHeaders(headers);
Response<ResponseBody> response = environment.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());
}
}addParam
addParam adds one query parameter to the environment, for the find request.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter, for example include_count. |
| value (required) | Object | Value of the query parameter, sent without URL encoding. |
Returns: Environment. The same environment, for chaining.
Validation
- There is no client-side validation.
- 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 in the query parameter map of the environment and sends no request.
- A second call with the same key replaces the value.
- Only find sends the map. fetch, create, update and delete send no query parameters.
- The SDK sends the value as it is, without URL encoding. Encode a value that holds reserved characters, such as &, = or +, before you pass it.
- The parameter stays on the environment for every later find call. Use the removeParam method to drop it.
- Get all environments accepts include_count, asc, desc and query.
Example
Basic usage: include the total count of environments
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class CountEnvironments {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Environment environments = stack.environment().addParam("include_count", true);
Response<ResponseBody> response = environments.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());
}
}Encoded value: pass a JSON query
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.net.URLEncoder;
public class QueryEnvironments {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
// The SDK does not encode the value, so encode the JSON first
String query = URLEncoder.encode("{\"name\":\"production\"}", "UTF-8");
Environment environments = stack.environment().addParam("query", query);
Response<ResponseBody> response = environments.find().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}addParams
addParams adds several query parameters to the environment at once, for the find request.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Query parameter names and values to add. |
Returns: Environment. The same environment, for chaining.
Validation
- There is no client-side validation.
- 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 entry of params into the query parameter map of the environment and sends no request.
- An entry replaces a parameter with the same name. Parameters with other names stay.
- Only find sends the map, without URL encoding the values. The addParam method describes the accepted parameters.
- Later changes to your params map do not reach the environment, because addParams copies the entries.
Example
Basic usage: sort the environments and include the count
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class SortEnvironments {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
HashMap<String, Object> params = new HashMap<>();
params.put("asc", "created_at");
params.put("include_count", true);
Environment environments = stack.environment().addParams(params);
Response<ResponseBody> response = environments.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 adds a publishing environment to the stack.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | Environment details in an environment object: name and urls. |
Returns: Call<ResponseBody>. The request for the new environment, sent when you call execute().
Validation
- There is no client-side validation. create sends body unchanged.
- 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 an environment request (POST /environments) with body as the JSON request body.
- In body, the API expects the environment name and its urls. Each entry in urls pairs a language code (locale) with the base URL of the server (url).
- create ignores the environment name of the object, so call it on stack.environment().
- create sends no query parameters.
- The response body is the raw JSON that the API returns, with the new environment.
Example
Basic usage: add an environment with one URL
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateEnvironment {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
JSONObject url = new JSONObject();
url.put("locale", "en-us");
url.put("url", "https://staging.example.com/");
JSONArray urls = new JSONArray();
urls.add(url);
JSONObject environment = new JSONObject();
environment.put("name", "docs-test-staging");
environment.put("urls", urls);
JSONObject body = new JSONObject();
body.put("environment", environment);
Response<ResponseBody> response = stack.environment().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 one publishing environment from the stack.
Returns: Call<ResponseBody>. The request for deleting the environment, sent when you call execute().
Validation
- Throws NullPointerException if the environment has no name, as on stack.environment(), because delete builds the request path from the name.
- Throws IllegalStateException if the name is an empty string, 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
- One execute() sends one Delete environment request (DELETE /environments/{environment_name}) with the headers of the environment.
- delete sends no query parameters and no request body.
- The response body is the raw JSON that the API returns.
Example
Basic usage: delete an environment by name
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteEnvironment {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Environment environment = stack.environment("docs-test-staging");
Response<ResponseBody> response = environment.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());
}
}fetch
fetch builds the request that retrieves the details of one environment by its name.
Returns: Call<ResponseBody>. The request for the environment, sent when you call execute().
Validation
- Throws NullPointerException if the environment has no name, as on stack.environment(), because fetch builds the request path from the name.
- Throws IllegalStateException if the name is an empty string, 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
- One execute() sends one Get a single environment request (GET /environments/{environment_name}) with the headers of the environment.
- fetch sends no query parameters. Values from addParam do not reach this request.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Example
Basic usage: fetch one environment by name
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchEnvironment {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Environment environment = stack.environment("<ENVIRONMENT>");
Response<ResponseBody> response = environment.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());
}
}Edge case: an environment without a name throws before any request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
public class FetchEnvironmentWithoutName {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Environment environment = stack.environment();
try {
environment.fetch();
} catch (NullPointerException e) {
// Fires because stack.environment() holds no environment name
System.out.println("Pass the environment name to stack.environment(...)");
}
}
}find
find builds the request that lists every publishing environment of the stack.
Returns: Call<ResponseBody>. The request for all environments, 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 environments request (GET /environments) with the headers and query parameters of the environment.
- find ignores the environment name, so it works on stack.environment() and on stack.environment("<ENVIRONMENT>").
- The API accepts the query parameters include_count, asc and desc, and a query parameter with a query in JSON format.
- The SDK sends the parameter values without URL encoding. Encode a query value with java.net.URLEncoder before you pass it.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Example
Basic usage: list the environments of a stack
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListEnvironments {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Environment environments = stack.environment();
Response<ResponseBody> response = environments.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 sort: find environments by name, newest first, with a count
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.net.URLEncoder;
public class FindEnvironmentsByName {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
// The SDK does not encode query values, so encode the JSON query here
String query = URLEncoder.encode("{\"name\":\"production\"}", "UTF-8");
Environment environments = stack.environment()
.addParam("query", query)
.addParam("desc", "updated_at")
.addParam("include_count", true);
Response<ResponseBody> response = environments.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 the environment, so later find requests stop sending it.
| 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 environment does not hold leaves the map unchanged and does not throw.
Behavior
- Client-side only. removeParam deletes the entry from the query parameter map of the environment and sends no request.
- removeParam returns void, so it does not chain. Call it as a separate statement.
- Use the addParam method to add the parameter again.
Example
Basic usage: drop the count from later requests
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveEnvironmentParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
Environment environments = stack.environment().addParam("include_count", true);
environments.removeParam("include_count");
Response<ResponseBody> response = environments.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 or URLs of one environment.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Updated details in an environment object, for example urls. |
Returns: Call<ResponseBody>. The request for the updated environment, sent when you call execute().
Validation
- Throws NullPointerException if the environment has no name, as on stack.environment(), because update builds the request path from the name.
- Throws IllegalStateException if the name is an empty string, 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
- One execute() sends one Update environment request (PUT /environments/{environment_name}) with requestBody as the JSON request body.
- The API lets you change the environment name and its urls.
- After you rename an environment, open it again with the new name. The Environment object keeps the old name, so its next fetch, update or delete targets the old name.
- update sends no query parameters.
- The response body is the raw JSON that the API returns, with the updated environment.
Example
Basic usage: replace the URLs of an environment
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Environment;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateEnvironmentUrls {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>");
JSONObject url = new JSONObject();
url.put("locale", "en-us");
url.put("url", "https://www.example.com/");
JSONArray urls = new JSONArray();
urls.add(url);
JSONObject details = new JSONObject();
details.put("urls", urls);
JSONObject requestBody = new JSONObject();
requestBody.put("environment", details);
Environment environment = stack.environment("<ENVIRONMENT>");
Response<ResponseBody> response = environment.update(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());
}
}