Role

View as Markdown

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.

NameTypeDescription
key (required)String

Names the header.

Default: Not applicable
value (required)String

Sets the header value.

Default: Not applicable

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.

NameTypeDescription
headers (required)HashMap<String, String>

Maps each header name to its value.

Default: Not applicable

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.

NameTypeDescription
key (required)String

Names the query parameter.

Default: Not applicable
value (required)Object

Sets the parameter value, sent as its string form.

Default: Not applicable

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.

NameTypeDescription
params (required)HashMap<String, Object>

Maps each query parameter name to its value.

Default: Not applicable

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.

NameTypeDescription
requestBody (required)JSONObject

Holds the role details under a role key.

Default: Not applicable
requestBody.role.name (required)String

Names the new role.

Default: Not applicable
requestBody.role.descriptionString

Describes the role.

Default: API default
requestBody.role.rulesArray

Lists the actions the role allows on entries, fields and assets.

Default: API default

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.

NameTypeDescription
key (required)String

Names the query parameter to remove.

Default: Not applicable

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).

NameTypeDescription
requestBody (required)JSONObject

Holds the updated role details under a role key.

Default: Not applicable
requestBody.role.nameString

Renames the role.

Default: API default
requestBody.role.descriptionString

Changes the description.

Default: API default
requestBody.role.rulesArray

Replaces the actions the role allows.

Default: API default

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());
    }
}