Contentstack

View as Markdown

Contentstack

Contentstack creates the Stack object that every content request in the Android Delivery SDK starts from. Use this class to

  • create a stack from your API key, delivery token, and environment
  • create a stack with extra settings, such as a region, a host, or a branch, through Config
  • look up the URL of a Contentstack API service in a region

Every method is static. The class has no public constructor, so you call each method on the class name, for example Contentstack.stack(...).

getContentstackEndpoint

getContentstackEndpoint returns the URL of one Contentstack API service in a region, for example the Content Delivery host in the EU region.

NameTypeDescription
region (required)String

Region ID or alias, such as eu or azure-na.

Default: Not applicable
service (required)String

Service name, such as contentDelivery.

Default: Not applicable
omitHttpsboolean

Returns the bare host without https:// when true.

Default: false (the two-argument overload keeps https://)

Returns: String. The URL of the service in the region.

Validation

  • Throws IllegalArgumentException if region is null, empty, or not a known region, because the SDK can only return a URL that its region list holds.
  • Throws IllegalArgumentException if the region has no service named service.
  • Throws IllegalStateException if the SDK cannot load its region list.

Known issue In 4.4.0, the SDK package does not include its region list, so the first lookup downloads it on the calling thread. On the main thread Android blocks the download, and this method throws IllegalStateException on that call and on every later lookup in the process. Call it from a background thread.

Behavior

  • getContentstackEndpoint calls Endpoint.getContentstackEndpoint with the same arguments and returns its result. That page describes the region name rules and the region list.
  • Client-side only. The method sends no Content Delivery API request.
  • Use the getContentstackEndpoints method to get every service URL in a region at once.

Example

Basic usage: get the Content Delivery URL for the EU region

import android.util.Log;

import com.contentstack.sdk.Contentstack;

new Thread(() -> {
    try {
        String url = Contentstack.getContentstackEndpoint("eu", "contentDelivery");
        Log.d("Contentstack", url);
    } catch (IllegalArgumentException e) {
        // The region or the service is not in the region list
        Log.e("Contentstack", "Unknown region or service: " + e.getMessage());
    } catch (IllegalStateException e) {
        // The SDK could not load the region list
        Log.e("Contentstack", "Region list unavailable: " + e.getMessage());
    }
}).start();

All parameters: get the bare host to pass to setHost

import android.util.Log;

import com.contentstack.sdk.Contentstack;

new Thread(() -> {
    try {
        String host = Contentstack.getContentstackEndpoint("azure-na", "contentDelivery", true);
        Log.d("Contentstack", host);
    } catch (RuntimeException e) {
        Log.e("Contentstack", e.getMessage());
    }
}).start();

getContentstackEndpoints

getContentstackEndpoints returns the URL of every Contentstack API service in a region, with service names as keys.

NameTypeDescription
region (required)String

Region ID or alias, such as eu or azure-na.

Default: Not applicable
omitHttpsboolean

Returns bare hosts without https:// when true.

Default: false (the one-argument overload keeps https://)

Returns: Map. Every service URL in the region, with service names as keys.

Validation

  • Throws IllegalArgumentException if region is null, empty, or not a known region, because the SDK can only return URLs that its region list holds.
  • Throws IllegalStateException if the SDK cannot load its region list.

Known issue In 4.4.0, the SDK package does not include its region list, so the first lookup downloads it on the calling thread. On the main thread Android blocks the download, and this method throws IllegalStateException on that call and on every later lookup in the process. Call it from a background thread.

Behavior

  • getContentstackEndpoints calls Endpoint.getAllEndpoints with the same arguments and returns its result. That page describes the map and the region name rules.
  • The declared return type is Map<String, String>.
  • Client-side only. The method sends no Content Delivery API request.
  • Use the getContentstackEndpoint method to get the URL of one service.

Example

Basic usage: list the service URLs of the EU region

import android.util.Log;

import com.contentstack.sdk.Contentstack;

import java.util.Map;

new Thread(() -> {
    try {
        Map<String, String> endpoints = Contentstack.getContentstackEndpoints("eu");
        for (Map.Entry<String, String> endpoint : endpoints.entrySet()) {
            Log.d("Contentstack", endpoint.getKey() + ": " + endpoint.getValue());
        }
    } catch (IllegalArgumentException e) {
        // The region is not in the region list
        Log.e("Contentstack", "Unknown region: " + e.getMessage());
    } catch (IllegalStateException e) {
        // The SDK could not load the region list
        Log.e("Contentstack", "Region list unavailable: " + e.getMessage());
    }
}).start();

All parameters: list bare hosts without https://

import android.util.Log;

import com.contentstack.sdk.Contentstack;

import java.util.Map;

new Thread(() -> {
    try {
        Map<String, String> hosts = Contentstack.getContentstackEndpoints("gcp-na", true);
        Log.d("Contentstack", "Images host: " + hosts.get("images"));
    } catch (RuntimeException e) {
        Log.e("Contentstack", e.getMessage());
    }
}).start();

stack

stack creates the Stack object that sends every content request for one stack and environment.

NameTypeDescription
context (required)Context

Android context that the SDK uses for requests and its cache.

Default: Not applicable
apiKey (required)String

API key of the stack.

Default: Not applicable
deliveryToken (required)String

Delivery token scoped to the environment.

Default: Not applicable
environment (required)String

Publishing environment to read content from.

Default: Not applicable
configConfig

Region, host, branch, and other settings for the stack.

Default: A new Config with region US

Returns: Stack. A new stack object.

Validation

  • Throws NullPointerException if context, apiKey, deliveryToken, or environment is null, because the SDK checks each argument before it builds the stack.
  • In the five-argument overload, also throws NullPointerException if config is null.
  • Throws Exception only when apiKey, deliveryToken, and environment are all empty strings. One or two empty values pass the check, and the API rejects the first request that the stack sends.
  • stack declares throws Exception, so Java requires a try block or a throws clause around every call.
  • The SDK does not check the credentials against the API. A wrong API key, token, or environment surfaces as an Error in the callback of the first request, for example fetch on an entry.

Known issue In 4.4.0, the SDK package does not include its region list, so stack downloads the list on the calling thread when you have not called setHost. On the main thread Android blocks the download, and stack throws IllegalStateException, then throws it again on every later call in the process. Call setHost on a Config and pass it to the five-argument overload, or call stack on a background thread.

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

Behavior

  • stack sends no content request. It stores the settings that later requests use.
  • The SDK sends these headers on each request from the stack:
    • api_key with apiKey
    • access_token with deliveryToken
    • environment with environment, which entry, query, asset, and content type requests also copy into the environment query parameter
    • branch, when you called setBranch
    • x-header-ea, when you called earlyAccess
  • The host comes from setHost when you called it. Otherwise stack looks up the Content Delivery host for the region in the Config. See the setRegion method for the region hosts.
  • stack writes the host it chose and the environment value back into the Config you pass, so getHost and getEnvironment return them after the call.
  • The SDK reads the Config once, during this call. A change to the Config afterwards does not reach the stack.
  • Each call returns a new Stack and schedules a cleanup that runs at once and then daily, deleting cached responses 24 hours old or older. Create the stack once and reuse it.
  • The Get a single entry request and the other Content Delivery API requests read the API key from the api_key header and the token from access_token. They take the environment as the environment query parameter.

Example

Basic usage: create a stack and fetch an entry

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
    entry.fetch(new EntryResultCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, Error error) {
            if (error == null) {
                Log.d("Contentstack", entry.getTitle());
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

All parameters: create a stack with a Config

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Stack;

try {
    Config config = new Config();
    config.setHost("eu-cdn.contentstack.com");
    config.setBranch("<BRANCH>");
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Log.d("Contentstack", "Host: " + config.getHost());
} catch (Exception e) {
    Log.e("Contentstack", e.getMessage());
}

Edge case: create the stack on a background thread

import android.util.Log;

import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Stack;

new Thread(() -> {
    try {
        // Off the main thread, the SDK can download its region list
        Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");
        Log.d("Contentstack", "Stack ready");
    } catch (Exception e) {
        Log.e("Contentstack", e.getMessage());
    }
}).start();