Contentstack
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.
| Name | Type | Description |
|---|---|---|
| region (required) | String | Region ID or alias, such as eu or azure-na. |
| service (required) | String | Service name, such as contentDelivery. |
| omitHttps | boolean | Returns the bare host without https:// when true. |
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.
| Name | Type | Description |
|---|---|---|
| region (required) | String | Region ID or alias, such as eu or azure-na. |
| omitHttps | boolean | Returns bare hosts without https:// when true. |
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.
| Name | Type | Description |
|---|---|---|
| context (required) | Context | Android context that the SDK uses for requests and its cache. |
| apiKey (required) | String | API key of the stack. |
| deliveryToken (required) | String | Delivery token scoped to the environment. |
| environment (required) | String | Publishing environment to read content from. |
| config | Config | Region, host, branch, and other settings for the stack. |
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();