Role

Note: Only BeBanjo accounts configured for User Permissions will expose roles in the API.

A Role represents a group of actions a user can perform over the catalogue, each of those actions are represented by different keys.

This is how a role looks like:

<?xml version="1.0" encoding="UTF-8"?>
<role>
  <id type="integer">3</id>
  <name>Contributor</name>
  <keys>contributor:read contributor:create contributor:update contributor:delete item:create item:detach share</keys>
  <level type="integer">2</level>
  <link rel="self" href="https://movida.bebanjo.net/api/roles/3"/>
</role>

{
  "resource_type": "role",
  "id": 3,
  "name": "Contributor",
  "keys": "contributor:read contributor:create contributor:update contributor:delete item:create item:detach share",
  "level": 2,
  "self_link": "https://movida.bebanjo.net/api/roles/3"
}

The self link is pointing to the role itself, and it is a unique URL that will not change overtime.

Valid attributes

• id (required): BeBanjo internal identifier of the role.

• name (required): the name of the role.

• keys (required): the keys associated to the role. It includes all the keys associated to roles with lower level, plus specific additional keys.

• level (required): the level of the role. A user with certain role level can be granted with item level permissions with minor or equal level.

Get a list of all roles in the current account

Roles are linked from the root of the API, through the link identified with the rel="roles" attribute:

<?xml version="1.0" encoding="UTF-8"?>
<movida>
  <!-- ... -->
  <link rel="roles" href="https://movida.bebanjo.net/api/roles">
</movida>

{
  // ...
  "roles_link": "https://movida.bebanjo.net/api/roles",
  // ...
}

Following that link, we can fetch the list of roles in the current account.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/roles

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/roles

<?xml version="1.0" encoding="UTF-8"?>
<roles type="array">
  <total-entries>53</total-entries>
  <link rel="next" href="https://movida.bebanjo.net/api/roles?page=2"/>
  <role>
    <id type="integer">1</id>
    <name>Viewer</name>
    <keys>contributor:read</keys>
    <level type="integer">0</level>
    <link rel="self" href="https://movida.bebanjo.net/api/roles/1"/>
  </role>
  <role>
    <id type="integer">2</id>
    <name>Editor</name>
    <keys>contributor:read contributor:create contributor:update</keys>
    <level type="integer">1</level>
    <link rel="self" href="https://movida.bebanjo.net/api/roles/2"/>
  </role>
  <!-- ... -->
</roles>

{
  "total_entries": 53,
  "next_link": "https://movida.bebanjo.net/api/roles?page=2",
  "entries": [
    {
      "resource_type": "role",
      "id": 1,
      "name": "Viewer",
      "keys": "contributor:read",
      "level": 0,
      "self_link": "https://movida.bebanjo.net/api/roles/1"
    }
    {
      "resource_type": "role",
      "id": 2,
      "name": "Editor",
      "keys": "contributor:read contributor:create contributor:update",
      "level": 1,
      "self_link": "https://movida.bebanjo.net/api/roles/2"
    },
    // ...
  ]
}

Note: This is a paginated resource. By default, only 50 roles will be included in each page but you can override this default by using the per_page parameter described in the next section. The total-entries attribute will indicate the total number of entries and the links rel="next" and rel="prev" should be used to get the next and the previous pages.

You can filter the list of roles returned using the following attributes:

• per_page: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50.

Get a single role given its URL

The self link of a role contains a URL that will allow us to fetch that individual role:

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/roles/3

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/roles/3

<?xml version="1.0" encoding="UTF-8"?>
<role>
  <id type="integer">3</id>
  <name>Contributor</name>
  <keys>contributor:read contributor:create contributor:update contributor:delete item:create item:detach share</keys>
  <level type="integer">2</level>
  <link rel="self" href="https://movida.bebanjo.net/api/roles/3"/>
</role>

{
  "resource_type": "role",
  "id": 3,
  "name": "Contributor",
  "keys": "contributor:read contributor:create contributor:update contributor:delete item:create item:detach share",
  "level": 2,
  "self_link": "https://movida.bebanjo.net/api/roles/3"
}