Authorization Service - Role RESTful APIs - Release v0.7 Alpha

Owned by Adaptavist ScriptRunner for Confluence Cloud
Last updated: Oct 27, 2022 by Megan Forbes
2 min read

REST-based API for Role

The Authorization Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual role instances, and on the associated permission and account instances. These follow the Common model for CollectionSpace REST services.

Note that the authorization service does not support extensible schema. That means, the request or response contains the payload only from a single schema, the Content-type header of application/xml is used.

Role CRUD+L services

Create a Role

Creates a new Role record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Role record. Follows standard Create model. See the documentation of the Role schema, below. Example:

POST /cspace-services/authorization/roles HTTP/1.1
Read a Role

Reads an existing Role record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Role schema, below. Example:

GET /cspace-services/authorization/roles/{id} HTTP/1.1
Update a Role

Updates an existing Role record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Role schema, below. See also the notes on immutable accounts, below. Example:

PUT /cspace-services/authorization/roles/{id} HTTP/1.1
Delete a Role

Deletes an existing Role record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. See also the notes on immutable accounts, below. Example:

DELETE /cspace-services/authorization/roles/{id} HTTP/1.1
List Role instances

Lists existing Role records, with summary information for each. Follows standard List model. See the documentation of the Role-List schema, below. List supports the following common parameters for List results, pagination controls and query filters:

  • pgSz for page size
  • pgNum for page size
  • r for role name

Examples:

GET /cspace-services/authorization/roles/ HTTP/1.1
GET /cspace-services/authorization/roles/?pgSz=10 HTTP/1.1

Role REST payload schemas

Role instance schema

Create and Update should use the following schema.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:role xmlns:ns2="http://collectionspace.org/services/authorization">
  <roleName>ROLE_USERS_TEST</roleName>
  <description>this role is for test users</description>
</ns2:role>

Read will return the above, plus additional fields (csid) for access:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:role xmlns:ns2="http://collectionspace.org/services/authorization" csid="d12decdb-0bc9-4460-94cb-f64982538356">
  <roleName>ROLE_USERS_TEST</roleName>
  <description>this role is for test users</description>
  <createdAt>2010-04-05T16:40:47.000</createdAt>
</ns2:role>

There are several pre-built roles that have protection values set to immutable. These flags cannot be set on CREATE nor changed on UPDATE, but they can be read for the pre-built roles. If metadataProtection is set to "immutable" then any changes to the metadata on UPDATE will be discarded, and delete will be disallowed. If permsProtection is set to "immutable" then any changes (add or delete) to associated roles will be disallowed. E.g.:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:role xmlns:ns2="http://collectionspace.org/services/authorization" csid="d12decdb-0bc9-4460-94cb-f64982538356">
  <displayName>TENANT_READER</displayName>
  <roleName>ROLE_1_TENANT_READER</roleName>
  <description>generated tenant read only role</description>
  <metadataProtection>immutable</metadataProtection>
  <permsProtection>immutable</permsProtection>
  <createdAt>2011-08-22T15:01:25.422</createdAt>
</ns2:role>
Role-List schema

List (and variants) will return the following schema. Note the standard pagination support.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:roles_list xmlns:ns2="http://collectionspace.org/services/authorization">
<role csid="6f3f6c62-0c49-439d-b1e1-99de050ac523">
  <roleName>ROLE_COLLECTIONS_MANGER_TEST</roleName>
  <createdAt>2010-04-05T16:42:51.000</createdAt>
</role>
<role csid="c5fe90ee-322e-41f6-b6ac-fcf3d96a5beb">
  <roleName>ROLE_COLLECTIONS_CURATOR_TEST</roleName>
  <createdAt>2010-04-05T16:42:53.000</createdAt>
</role>
</ns2:roles_list>