Alias

View as Markdown

Alias

A branch alias points to one branch of a stack, the target branch. Your frontend code can use the alias UID to read content from whichever branch the alias points to. Use this class to

  • list every alias in the stack
  • fetch one alias and its target branch
  • assign an alias to a branch, or delete an alias

The alias method on Stack returns a new Alias. It has two forms:

NameTypeDescription
aliasUidStringUID of the alias. Omit it to work on all aliases.

Additional Resource The Aliases section of the Content Management API (CMA) reference describes every alias request and its response.

addHeader

addHeader adds one request header to the requests that this alias object sends.

NameTypeDescription
key (required)String

Name of the request header.

Default: Not applicable
value (required)String

Value of the request header.

Default: Not applicable

Returns: Alias. The same alias, 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 alias object and makes no request.
  • Every request method on this alias object sends every stored header.
  • stack.alias() 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: set the management token on the alias object only

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

import java.io.IOException;

public class FetchAliasWithToken {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        // A key that starts with blt becomes the api_key header
        Alias alias = client.stack("<API_KEY>").alias("<ALIAS_UID>")
                .addHeader("authorization", "<MANAGEMENT_TOKEN>");

        Response<ResponseBody> response = alias.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 alias object sends.

NameTypeDescription
headers (required)HashMap<String, String>

Header names and values to add.

Default: Not applicable

Returns: Alias. The same alias, 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 alias object and makes no request.
  • Every request method on this alias 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.Alias;
import okhttp3.ResponseBody;
import retrofit2.Response;

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

public class ListAliasesWithHeaders {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        HashMap<String, String> headers = new HashMap<>();
        headers.put("authorization", "<MANAGEMENT_TOKEN>");
        // A key that starts with blt becomes the api_key header
        Alias alias = client.stack("<API_KEY>").alias().addHeaders(headers);

        Response<ResponseBody> response = alias.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 alias object sends.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)Object

Value of the query parameter.

Default: Not applicable

Returns: Alias. The same alias, 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 alias object and makes no request.
  • find and delete send every stored parameter. fetch and update 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. Alias has no public method that removes a parameter, so call stack.alias() again to start without one.

Example

Basic usage: include the total count when you list aliases

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

import java.io.IOException;

public class CountAliases {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Alias alias = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").alias()
                .addParam("include_count", true);

        Response<ResponseBody> response = alias.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 alias object sends.

NameTypeDescription
params (required)HashMap<String, Object>

Query parameter names and values to add.

Default: Not applicable

Returns: Alias. The same alias, 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 alias object and makes no request.
  • find and delete send every stored parameter. fetch and update 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: page through aliases with limit and skip

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

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

public class PageAliases {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        HashMap<String, Object> params = new HashMap<>();
        params.put("limit", 10);
        params.put("skip", 10);
        params.put("include_count", true);
        Alias alias = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").alias().addParams(params);

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

delete

delete builds the request that deletes one branch alias.

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

Validation

  • Throws NullPointerException when the alias has no UID, because the request path needs one. Create the object with stack.alias("<ALIAS_UID>").
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API rejects the request without the force query parameter set to true, because force=true confirms the deletion. Add it with addParam.

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

Behavior

Warning delete removes the alias from the stack. The Aliases API has no request that restores a deleted alias. Code that reads content through the alias UID needs a new alias before it works again.

  • One execute() sends one Delete an alias request (DELETE /v3/stacks/branch_aliases/{branch_alias_uid}) with the headers and query parameters on this object.
  • The API accepts only an authtoken for this request. Log in with client.login before you call delete.
  • The response body is the raw JSON from the API, with a notice message.

Example

Basic usage: delete an alias with the force parameter

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

import java.io.IOException;

public class DeleteAlias {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        // A key that starts with blt becomes the api_key header
        Alias alias = client.stack("<API_KEY>").alias("<ALIAS_UID>")
                .addParam("force", true);

        Response<ResponseBody> response = alias.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 one branch alias and its target branch.

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

Validation

  • Throws NullPointerException when the alias has no UID, because the request path needs one. Create the object with stack.alias("<ALIAS_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 alias request (GET /v3/stacks/branch_aliases/{branch_alias_uid}) with the headers on this object.
  • fetch does not send the query parameters from addParam.
  • The response body is the raw JSON from the API, with the alias under a branch_alias key. Its uid names the target branch.

Example

Basic usage: fetch one alias and its target branch

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

import java.io.IOException;

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

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

find

find builds the request that lists every branch alias in the stack.

Returns: Call<ResponseBody>. The request for the stack's aliases, 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 aliases request (GET /v3/stacks/branch_aliases) 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:
    • limit: the maximum number of aliases to return.
    • skip: the number of aliases to skip.
    • include_count: true adds the total number of aliases to the response.
  • The SDK sends one request and does not page through results. Raise skip by limit on each call to read the next page.
  • The response body is the raw JSON from the API, with the aliases under a branch_aliases array. Each alias names its target branch in uid and its own UID in alias.

Example

Basic usage: list every alias

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

import java.io.IOException;

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

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

Pagination: read the second page of ten aliases with a total count

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

import java.io.IOException;

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

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

update

update builds the request that assigns an alias to a target branch, or points an existing alias at a new branch.

NameTypeDescription
body (required)JSONObject

Request body with the alias under a branch_alias key.

Default: Not applicable
body.branch_alias.target_branch (required)String

UID of the branch the alias points to.

Default: Not applicable

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

Validation

  • There is no client-side validation. update does not check body.
  • 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

  • Known issue: In 1.16.0, update sends PUT /v3/stacks/branch_aliases without an alias UID, and ignores the UID you pass to stack.alias("<ALIAS_UID>"). The Assign an alias request needs the alias UID in its path, PUT /v3/stacks/branch_aliases/{branch_alias_uid}. Assign the alias in the Contentstack app, or send that request with an HTTP client.
  • update sends body as the JSON body with the headers on this object. It does not send the query parameters from addParam.
  • The API accepts only an authtoken for this request, and only stack owners, admins, and developers can assign an alias.

Example

Basic usage: build the request that points an alias at a branch

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

import java.io.IOException;

public class AssignAlias {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        // A key that starts with blt becomes the api_key header
        Alias alias = client.stack("<API_KEY>").alias("<ALIAS_UID>");

        JSONObject details = new JSONObject();
        details.put("target_branch", "<BRANCH>");
        JSONObject body = new JSONObject();
        body.put("branch_alias", details);

        // See the Known issue above: in 1.16.0 the request path has no alias UID
        Response<ResponseBody> response = alias.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());
    }
}