Endpoint

View as Markdown

Endpoint

Endpoint returns the URLs of Contentstack API services for a region, so your app does not hard-code a host such as eu-cdn.contentstack.com. Use this class to

  • get the Content Delivery URL, or the URL of another service, for one region
  • get every service URL of a region at once
  • get a bare host to pass to setHost

Every method is static, and the class has no public constructor. Contentstack exposes the same lookups as getContentstackEndpoint and getContentstackEndpoints, and stack uses them to find the Content Delivery host of the region in Config.

getAllEndpoints

getAllEndpoints 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 only spaces, because the SDK needs a region name to search for.
  • Throws IllegalArgumentException if no region ID or alias matches region.
  • Throws IllegalStateException if the SDK cannot load its region list, or if the list it loads is not valid JSON.

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

  • Client-side only, apart from the one-time region list download that the Endpoint class page describes. The method sends no Content Delivery API request.
  • The declared return type is Map<String, String>, and the map is a LinkedHashMap, so it keeps the order of the services in the region list. Each call returns a new map, and a change to it does not affect later calls.
  • Keys are service names such as contentDelivery, contentManagement, and images. The set of keys differs between regions.
  • omitHttps removes the leading https:// (or http://) from every value.
  • Use the getContentstackEndpoint method to read one service.

Example

Basic usage: list the service URLs of the EU region

import android.util.Log;

import com.contentstack.sdk.Endpoint;

import java.util.Map;

new Thread(() -> {
    try {
        Map<String, String> endpoints = Endpoint.getAllEndpoints("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.Endpoint;

import java.util.Map;

new Thread(() -> {
    try {
        Map<String, String> hosts = Endpoint.getAllEndpoints("us", true);
        Log.d("Contentstack", "Content Delivery host: " + hosts.get("contentDelivery"));
    } catch (RuntimeException e) {
        Log.e("Contentstack", e.getMessage());
    }
}).start();

getContentstackEndpoint

getContentstackEndpoint returns the URL of one Contentstack API service in a region, for example https://eu-cdn.contentstack.com for the Content Delivery service 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 only spaces, because the SDK needs a region name to search for.
  • Throws IllegalArgumentException if no region ID or alias matches region, or if the region has no service named service. Service names are case-sensitive.
  • Throws IllegalStateException if the SDK cannot load its region list, or if the list it loads is not valid JSON.

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

  • Client-side only, apart from the one-time region list download that the Endpoint class page describes. The method sends no Content Delivery API request.
  • omitHttps removes the leading https:// (or http://) from the URL. The result then fits setHost, which takes a host name without a scheme.
  • Some URLs carry a path after the host, for example the genAI service. Pass only a host to setHost, such as the contentDelivery value.
  • A region name that the list does not hold triggers the one download per process before the method throws, so a second unknown name fails without a download.
  • Use the getAllEndpoints method to read every service of a region at once.

Example

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

import android.util.Log;

import com.contentstack.sdk.Endpoint;

new Thread(() -> {
    try {
        String url = Endpoint.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 a bare host for another service

import android.util.Log;

import com.contentstack.sdk.Endpoint;

new Thread(() -> {
    try {
        // Region names ignore case and treat - and _ alike
        String host = Endpoint.getContentstackEndpoint("AZURE_EU", "graphqlDelivery", true);
        Log.d("Contentstack", host);
    } catch (RuntimeException e) {
        Log.e("Contentstack", e.getMessage());
    }
}).start();