Authorization Service - PermissionRole 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 PermissionRole

The Authorization Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update and delete) operations on individual permission and role instances. These follow the Common model for CollectionSpace REST services. However, on relationships between the permissions and roles, only CRD (create, read and delete) operations are supported. Also, there are some exceptions that are documented below.

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.

PermissionRole CRD services

The following description uses URI paths off of the permission service (/cspace-services/authorization/permissions). However, with the 0.7 release, similar functionality is also offered off of the role service (/cspace-services/authorization/roles). The example payloads would have given role (/cspace-services/authorization/roles/{csid}) associated with one or more permission(s) in that case. The payload schema remains the same.

Create a PermissionRole

Creates new relationship(s) between the given permission and role(s) from the PermissionRole record. Follows standard Read model except each relationship record is uniquely identified by the CollectionSpace IDs (CSID) of a permission and a role. Therefore, the returned id for create is of little value for further operations. However, the id is returned just for consistency reasons. See the documentation of the PermissionRole schema, below. Example:

POST /cspace-services/authorization/permissions/{csid}/permroles HTTP/1.1
Read a PermissionRole

Reads existing relationship(s) between the given permission and role(s). The permission is identified by its CollectionSpace ID (CSID). Follows standard Read model except that the permrolecsid is ignored by the service as a relationship does not have a CSID. You could use any non-empty string for permrolecsid. See the documentation of the PermissionRole schema, below. Example:

GET /cspace-services/authorization/permissions/{csid}/permroles/{permrolecsid} HTTP/1.1
Update a PermissionRole

Update is not supported on PermisisonRole relationship.

Delete a PermissionRole

Deletes existing relationship(s) between the given permission and role(s). The permission is identified by its CollectionSpace ID (CSID). Follows standard Delete model except that the permrolecsid is ignored by the service as a relationship does not have a CSID. You could use any non-empty string for permrolecsid. Note that this operation removes all the relationships between the given permission and roles. Example:

DELETE /cspace-services/authorization/permissions/{csid}/permroles/{permrolecsid} HTTP/1.1

PermissionRole REST payload schemas

PermissionRole instance schema

Create should use the following schema.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:permission_role xmlns:ns2="http://collectionspace.org/services/authorization">
  <permission>
    <permissionId>9ecac865-4ec5-4882-a153-a7e06ba4b975</permissionId>
    <resourceName>accounts</resourceName>
  </permission>
  <role>
    <roleId>081010b7-e949-4a6c-9b43-f8aaf7b671a1</roleId>
    <roleName>ROLE_CO2</roleName>
  </role>
  <role>
    <roleId>3772624d-1ab3-4e47-a26d-191fc6437410</roleId>
    <roleName>ROLE_CO1</roleName>
  </role>
</ns2:permission_role>

Read will return the above.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:permission_role xmlns:ns2="http://collectionspace.org/services/authorization">
  <permission>
    <permissionId>9ecac865-4ec5-4882-a153-a7e06ba4b975</permissionId>
  </permission>
  <role>
    <roleId>081010b7-e949-4a6c-9b43-f8aaf7b671a1</roleId>
    <roleName>ROLE_CO2</roleName>
  </role>
  <role>
    <roleId>3772624d-1ab3-4e47-a26d-191fc6437410</roleId>
    <roleName>ROLE_CO1</roleName>
  </role>
</ns2:permission_role>