Role
Role
A role is a set of permissions that applies to every user who holds it. The Roles class builds the Content Management API requests that manage the roles of one stack. Use this class to
- list the roles of a stack, with or without their rules and permissions
- read, create, update or delete one role
Call the roles method of the Stack class to get an instance.
addHeader
addHeader adds one header to every request that this Roles object builds.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Names the header. |
| value (required) | String | Sets the header value. |
Returns: Roles. The same role, for chaining.
Validation
- There is no client-side validation. addHeader stores any name and value.
- A null name or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
- 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 header on this object and sends no request.
- Every request method of Roles sends the header, together with the headers that the object copied from the stack, such as api_key and authorization.
- A second call with the same name replaces the value. A name that matches a stack header, such as branch, replaces that header for this object.
- The header stays on this object only. The stack and other objects keep their own headers.
Example
Basic usage: send an extra header with each request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class AddRoleHeader {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles();
roles.addHeader("X-Request-Id", "list-roles-01");
Response<ResponseBody> response = roles.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 every entry of a map as a header of the requests that this Roles object builds.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Maps each header name to its value. |
Returns: Roles. The same role, for chaining.
Validation
- Throws NullPointerException if the map is null, because addHeaders copies its entries.
- A null name or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
- 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 the entries into the headers of this object and sends no request.
- A name that already exists takes the new value. Headers that the map does not name stay as they are.
- Every request method of Roles sends the headers.
- The header stays on this object only. The stack and other objects keep their own headers.
- The addHeader method adds one header at a time.
Example
Basic usage: send two extra headers with each request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class AddRoleHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles();
HashMap<String, String> headers = new HashMap<>();
headers.put("X-Request-Id", "list-roles-01");
headers.put("X-Client-Name", "role-audit");
roles.addHeaders(headers);
Response<ResponseBody> response = roles.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 this Roles object, for the requests that send query parameters.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Names the query parameter. |
| value (required) | Object | Sets the parameter value, sent as its string form. |
Returns: Roles. The same role, for chaining.
Validation
- There is no client-side validation. addParam stores any key and value.
- A null key or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
- 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. addParam stores the pair on this object and sends no request.
- Only the following requests send the stored parameters: find.
- fetch, create, update and delete send no query parameters, so a value you add has no effect on them.
- Retrofit writes each value with its toString() form, so pass a String, a Boolean or a number.
- A second call with the same key replaces the value.
- The parameter stays on this object for every later request until removeParam removes it.
Example
Basic usage: include the rules of each role in the list
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class AddRoleParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles();
roles.addParam("include_rules", true);
Response<ResponseBody> response = roles.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 every entry of a map as a query parameter of this Roles object.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Maps each query parameter name to its value. |
Returns: Roles. The same role, for chaining.
Validation
- Throws NullPointerException if the map is null, because addParams copies its entries.
- A null key or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
- 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 the entries into the parameters of this object and sends no request.
- A key that already exists takes the new value. Parameters that the map does not name stay as they are.
- Only the following requests send the stored parameters: find.
- The addParam method adds one parameter at a time.
Example
Basic usage: include the rules and permissions of each role
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class AddRoleParams {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles();
HashMap<String, Object> query = new HashMap<>();
query.put("include_rules", true);
query.put("include_permissions", true);
roles.addParams(query);
Response<ResponseBody> response = roles.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());
}
}create
create creates a role in the stack from the details in the request body.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Holds the role details under a role key. |
| requestBody.role.name (required) | String | Names the new role. |
| requestBody.role.description | String | Describes the role. |
| requestBody.role.rules | Array | Lists the actions the role allows on entries, fields and assets. |
Returns: Call<ResponseBody>. The request that creates the role, sent when you call execute().
Validation
- There is no client-side validation. create sends the body unchanged.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without 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
- Sends POST /v3/roles with the body as JSON, as Create a role describes.
- The body can also carry the users, additional roles and permissions of the role, such as the content types, taxonomies, environments and languages it can access.
- Sends no query parameters.
- create ignores the UID of the instance. The API assigns the UID of the new role and returns it in the response body.
Example
Basic usage: create a role that can read the main branch
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateRole {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles();
JSONArray branches = new JSONArray();
branches.add("main");
JSONObject acl = new JSONObject();
acl.put("read", true);
JSONObject branchRule = new JSONObject();
branchRule.put("module", "branch");
branchRule.put("branches", branches);
branchRule.put("acl", acl);
JSONArray rules = new JSONArray();
rules.add(branchRule);
JSONObject role = new JSONObject();
role.put("name", "docs-test-reviewer");
role.put("description", "Reads content on the main branch");
role.put("rules", rules);
JSONObject body = new JSONObject();
body.put("role", role);
Response<ResponseBody> response = roles.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 deletes the role whose UID you passed to stack.roles(roleUid).
Returns: Call<ResponseBody>. The request that deletes the role, sent when you call execute().
Validation
- Throws IllegalAccessError if the instance has no role UID, or an empty one, because delete removes one role.
- 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
- Sends DELETE /v3/roles/{role_uid}, as Delete role describes.
- Sends no query parameters.
Example
Basic usage: delete one role
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteRole {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles role = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles("<ROLE_UID>");
Response<ResponseBody> response = role.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 retrieves the role whose UID you passed to stack.roles(roleUid).
Returns: Call<ResponseBody>. The request for the role, sent when you call execute().
Validation
- Throws IllegalAccessError if the instance has no role UID, or an empty one, because fetch reads one role. Get the instance with stack.roles(roleUid).
- 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
- Sends GET /v3/roles/{role_uid}, as Get a single role describes.
- Sends no query parameters. Values from addParam do not reach this request.
- The response body is the raw JSON of the API, with the role under its role key.
Limitations
- Does not send include_permissions or include_rules, which the API accepts on this request. Call find with those parameters instead.
Example
Basic usage: read one role
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchRole {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles role = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles("<ROLE_UID>");
Response<ResponseBody> response = role.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());
}
}Edge case: call fetch on an instance without a UID
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
public class FetchRoleWithoutUid {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles();
try {
roles.fetch();
} catch (IllegalAccessError e) {
// Thrown before any request, because the instance holds no role UID
System.out.println("No role UID: " + e.getMessage());
}
}
}find
find lists the roles of the stack, with the query parameters that you add to this object.
Returns: Call<ResponseBody>. The request for all roles in 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
- Sends GET /v3/roles with every query parameter stored on this object, as Get all roles describes.
- Add query parameters with addParam or addParams before you call find. The API accepts the following three:
- include_permissions: set to true to include the permissions of each role.
- include_rules: set to true to include the rules of each role.
- query: a query in JSON format that filters the roles.
- The response body is the raw JSON of the API, with the roles in its roles array. The SDK does not map it to a typed object.
- find ignores the UID of the instance, so it lists every role on stack.roles(roleUid) too.
Example
Basic usage: list the roles of a stack
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindRoles {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles();
Response<ResponseBody> response = roles.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());
}
}Query parameters: include the rules and permissions of each role
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindRolesWithRules {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles()
.addParam("include_rules", true)
.addParam("include_permissions", true);
Response<ResponseBody> response = roles.find().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}removeParam
removeParam removes one query parameter from this Roles object.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Names the query parameter to remove. |
Returns: void. This method returns nothing.
Validation
- There is no client-side validation. A key that the object does not hold, or a null key, changes nothing.
- The change applies to the next request that sends query parameters, and an invalid remaining value surfaces as an API error when you call execute() on it.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. removeParam deletes the key from the parameters of this object and sends no request.
- Later calls to find no longer send the parameter.
- removeParam returns void, so it does not chain. Call it as its own statement.
- The object keeps every other parameter and every header.
Example
Basic usage: stop sending a query parameter
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveRoleParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles roles = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles();
roles.addParam("include_rules", true).addParam("include_permissions", true);
// Later requests send include_rules only
roles.removeParam("include_permissions");
Response<ResponseBody> response = roles.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 changes the details of the role whose UID you passed to stack.roles(roleUid).
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Holds the updated role details under a role key. |
| requestBody.role.name | String | Renames the role. |
| requestBody.role.description | String | Changes the description. |
| requestBody.role.rules | Array | Replaces the actions the role allows. |
Returns: Call<ResponseBody>. The request that updates the role, sent when you call execute().
Validation
- Throws IllegalAccessError if the instance has no role UID, or an empty one, because update changes one role.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without 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
- Sends PUT /v3/roles/{role_uid} with the body as JSON, as Update role describes.
- The body can also carry the users, additional roles and permissions of the role.
- Sends no query parameters.
Limitations
- Does not change a system role. The API keeps the pre-existing system roles as they are.
Example
Basic usage: rename a role and change its description
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Roles;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateRole {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
Roles role = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").roles("<ROLE_UID>");
JSONObject details = new JSONObject();
details.put("name", "docs-test-senior-reviewer");
details.put("description", "Reviews content before it goes live");
JSONObject body = new JSONObject();
body.put("role", details);
Response<ResponseBody> response = role.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());
}
}