DeliveryToken
DeliveryToken
A DeliveryToken manages the delivery tokens of one stack. A delivery token gives read-only access to the published content of the environments in its scope, through the Content Delivery API (CDA).
Use this class to
- list the delivery tokens of a stack
- fetch the details of one delivery token
- create a delivery token for an environment and a branch
- update or delete a delivery token
addHeader
addHeader adds one header to every request of this delivery token object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header, for example authtoken. |
| value (required) | String | Value to send in the header. |
Returns: DeliveryToken. The same delivery token object, 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 pair in the object's header map and sends no request.
- Every request method of the object sends the header: find, fetch, create, update and delete.
- A second call with the same key replaces the value. A key that the stack already set, such as api_key, takes the new value for this object only.
- The header does not reach the stack or other token objects.
Example
Basic usage: send an authtoken that you already hold
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.DeliveryToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeliveryTokensWithAuthtoken {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>");
// The client did not log in, so pass the authtoken as a header
DeliveryToken deliveryTokens = stack.tokens().deliveryTokens().addHeader("authtoken", "<AUTHTOKEN>");
Response<ResponseBody> response = deliveryTokens.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 this delivery token object.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names and values to add. |
Returns: DeliveryToken. The same delivery token object, 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 into the object's header map and sends no request.
- Every request method of the object sends the headers: find, fetch, create, update and delete.
- An entry whose name already exists replaces the earlier value. Headers that the map does not name stay unchanged.
Example
Basic usage: send the API key and authtoken as headers
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.DeliveryToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class DeliveryTokensWithHeaders {
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("authtoken", "<AUTHTOKEN>");
DeliveryToken deliveryTokens = stack.tokens().deliveryTokens().addHeaders(headers);
Response<ResponseBody> response = deliveryTokens.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 stores one query parameter on this delivery token object. No request of the class sends it.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter. |
| value (required) | Object | Value of the query parameter. |
Returns: DeliveryToken. The same delivery token object, for chaining.
Validation
- There is no client-side validation.
- No request sends the value, so an invalid value causes no error.
Behavior
- Client-side only. addParam stores the value in the object's query parameter map and sends no request.
- No request method of DeliveryToken sends that map. The value does not reach the API from find, fetch, create, update or delete.
- To send a query parameter, such as create_with_preview_token on Create delivery token, use an HTTP client outside the SDK.
Example
Edge case: the parameter does not reach the request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.DeliveryToken;
import com.contentstack.cms.stack.Stack;
public class DeliveryTokenParamNotSent {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>");
DeliveryToken deliveryTokens = stack.tokens().deliveryTokens().addParam("create_with_preview_token", true);
// request() builds the request without sending it. The URL has no query string.
System.out.println(deliveryTokens.find().request().url());
}
}addParams
addParams stores several query parameters on this delivery token object. No request of the class sends them.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Query parameter names and values to store. |
Returns: DeliveryToken. The same delivery token object, for chaining.
Validation
- There is no client-side validation.
- No request sends the values, so an invalid value causes no error.
Behavior
- Client-side only. addParams stores the value in the object's query parameter map and sends no request.
- No request method of DeliveryToken sends that map. The value does not reach the API from find, fetch, create, update or delete.
- To send a query parameter, such as create_with_preview_token on Create delivery token, use an HTTP client outside the SDK.
Example
Edge case: the parameters do not reach the request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.DeliveryToken;
import com.contentstack.cms.stack.Stack;
import java.util.HashMap;
public class DeliveryTokenParamsNotSent {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
Stack stack = client.stack("<API_KEY>");
HashMap<String, Object> params = new HashMap<>();
params.put("create_with_preview_token", true);
DeliveryToken deliveryTokens = stack.tokens().deliveryTokens().addParams(params);
// request() builds the request without sending it. The URL has no query string.
System.out.println(deliveryTokens.find().request().url());
}
}create
create builds the request that creates a delivery token in the stack.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Token details in a token object, for example name, description and scope. |
Returns: Call<ResponseBody>. The request for the new delivery token, sent when you call execute().
Validation
- There is no client-side validation. create sends requestBody 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 Create delivery token request (POST /stacks/delivery_tokens) with the object's headers and requestBody as the JSON body.
- The API reference names the details of the token: its name, its description and its scope. The scope lists the environments the token reads, and the branches or aliases it can access, each with an acl of read.
- The API reference recommends one publishing environment per delivery token.
- create ignores the UID of the object.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Limitations
- Does not create a preview token. The Create delivery token request takes create_with_preview_token as a query parameter, and no DeliveryToken request sends query parameters.
Example
Basic usage: create a delivery token for one environment and branch
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 CreateDeliveryToken {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Stack stack = client.stack("<API_KEY>");
JSONObject read = new JSONObject();
read.put("read", true);
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONObject environmentScope = new JSONObject();
environmentScope.put("module", "environment");
environmentScope.put("environments", environments);
environmentScope.put("acl", read);
JSONArray branches = new JSONArray();
branches.add("<BRANCH>");
JSONObject branchScope = new JSONObject();
branchScope.put("module", "branch");
branchScope.put("branches", branches);
branchScope.put("acl", read);
JSONArray scope = new JSONArray();
scope.add(environmentScope);
scope.add(branchScope);
JSONObject token = new JSONObject();
token.put("name", "docs-test-delivery-token");
token.put("description", "Reads the published content of one environment");
token.put("scope", scope);
JSONObject body = new JSONObject();
body.put("token", token);
Response<ResponseBody> response = stack.tokens().deliveryTokens().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 delivery token.
| Name | Type | Description |
|---|---|---|
| isForce (required) | Boolean | Sends force=true to force the deletion. |
Returns: Call<ResponseBody>. The request for the delivery token deletion, sent when you call execute().
Overloads
- delete(): This overload takes no parameters. It sends force=false.
- delete(Boolean isForce)
Validation
- delete() throws NullPointerException if the object holds no UID, as from deliveryTokens(), because it deletes one token by its UID.
- delete(Boolean) does not check the UID. On an object without a UID, execute() throws before it sends anything, because the request path needs the UID.
- Neither overload checks for an empty string. An empty UID sends the request with no token UID in the path.
- 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 delivery token request (DELETE /stacks/delivery_tokens/{token_uid}) with the object's headers.
- delete() sends the force query parameter as false. delete(Boolean) sends the value of isForce. Pass true to force the deletion, as the API reference describes.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Example
Basic usage: delete a delivery token
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.DeliveryToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteDeliveryToken {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Stack stack = client.stack("<API_KEY>");
DeliveryToken deliveryToken = stack.tokens().deliveryTokens("<TOKEN_UID>");
Response<ResponseBody> response = deliveryToken.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());
}
}Force the deletion
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.DeliveryToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ForceDeleteDeliveryToken {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Stack stack = client.stack("<API_KEY>");
DeliveryToken deliveryToken = stack.tokens().deliveryTokens("<TOKEN_UID>");
Response<ResponseBody> response = deliveryToken.delete(true).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}fetch
fetch builds the request that retrieves the details of one delivery token.
Returns: Call<ResponseBody>. The request for the delivery token, sent when you call execute().
Validation
- Throws NullPointerException if the object holds no UID, as from deliveryTokens(), because fetch works on one token by its UID.
- fetch does not check for an empty string. An empty UID sends the request with no token UID in the path.
- 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 delivery token request (GET /stacks/delivery_tokens/{token_uid}) with the object's headers.
- fetch sends no query parameters.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Example
Basic usage: fetch one delivery token
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.DeliveryToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchOneDeliveryToken {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Stack stack = client.stack("<API_KEY>");
DeliveryToken deliveryToken = stack.tokens().deliveryTokens("<TOKEN_UID>");
Response<ResponseBody> response = deliveryToken.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 delivery token of the stack.
Returns: Call<ResponseBody>. The request for all delivery tokens of the stack, 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 delivery tokens request (GET /stacks/delivery_tokens) with the object's headers.
- find sends no query parameters. Values from addParam do not reach this request.
- find ignores the UID of the object, so it lists every token from either kind of DeliveryToken.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Example
Basic usage: list the delivery tokens of a stack
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.DeliveryToken;
import com.contentstack.cms.stack.Stack;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class ListStackDeliveryTokens {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Stack stack = client.stack("<API_KEY>");
DeliveryToken deliveryTokens = stack.tokens().deliveryTokens();
Response<ResponseBody> response = deliveryTokens.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 updates the name, description or scope of one delivery token.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Updated token details in a token object, for example name, description and scope. |
Returns: Call<ResponseBody>. The request for the updated delivery token, sent when you call execute().
Validation
- Throws NullPointerException if the object holds no UID, as from deliveryTokens(), because update works on one token by its UID.
- update does not check for an empty string. An empty UID sends the request with no token UID in the path.
- 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 delivery token request (PUT /stacks/delivery_tokens/{token_uid}) with the object's headers and requestBody as the JSON body.
- The API reference names the fields you can change: the name, the description and the environment of the token.
- The scope can also limit the token to branches or aliases, through a branch module with a branches list or a branch_alias module with a branch_aliases list.
- The response body is the raw JSON that the API returns. Read it once with response.body().string().
Example
Basic usage: rename a delivery token and set its scope
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 UpdateDeliveryToken {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
client.login("<EMAIL>", "<PASSWORD>");
Stack stack = client.stack("<API_KEY>");
JSONObject read = new JSONObject();
read.put("read", true);
JSONArray environments = new JSONArray();
environments.add("<ENVIRONMENT>");
JSONObject environmentScope = new JSONObject();
environmentScope.put("module", "environment");
environmentScope.put("environments", environments);
environmentScope.put("acl", read);
JSONArray branches = new JSONArray();
branches.add("<BRANCH>");
JSONObject branchScope = new JSONObject();
branchScope.put("module", "branch");
branchScope.put("branches", branches);
branchScope.put("acl", read);
JSONArray scope = new JSONArray();
scope.add(environmentScope);
scope.add(branchScope);
JSONObject token = new JSONObject();
token.put("name", "docs-test-delivery-token-renamed");
token.put("description", "Reads the published content of one environment");
token.put("scope", scope);
JSONObject body = new JSONObject();
body.put("token", token);
Response<ResponseBody> response = stack.tokens().deliveryTokens("<TOKEN_UID>").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());
}
}