Environment

View as Markdown

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.

NameTypeDescription
key (required)String

Name of the header, for example authorization.

Default: Not applicable
value (required)String

Value to send in the header.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap<String, String>

Header names and values to add.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter, for example include_count.

Default: Not applicable
value (required)Object

Value of the query parameter, sent without URL encoding.

Default: Not applicable

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.

NameTypeDescription
params (required)HashMap<String, Object>

Query parameter names and values to add.

Default: Not applicable

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.

NameTypeDescription
body (required)JSONObject

Environment details in an environment object: name and urls.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Name of the query parameter to remove.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Updated details in an environment object, for example urls.

Default: Not applicable

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