Account Service - AccountRole RESTful APIs - Release v0.7 Alpha

Owned by Jessi Weithman
Aug 25, 2023
2 min read

REST-based API for AccountRole

The Account and Authorization Services offer a REST-based Application Programming Interface (API) to CRUD (create, read, update and delete) operations on individual account and role instances. These follow the Common model for CollectionSpace REST services. However, on the AccountRole relationship service, only CRD (create, read and delete) operations are supported.

Note that the AccountRole 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.

AccountRole CRD services

Create an AccountRole

Creates new relationship(s) between the given account and role(s) from the AccountRole record. Follows standard Read model except each relationship record is uniquely identified by the CollectionSpace IDs (CSID) of a account 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 AccountRole schema, below. Example:

POST /cspace-services/accounts/{csid}/accountroles HTTP/1.1
Read an AccountRole

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

GET /cspace-services/accounts/{csid}/accountroles/{accountrolecsid} HTTP/1.1
Update an AccountRole

Update is not supported on PermisisonRole relationship.

Delete an AccountRole

This is out of date - see comment at end of wiki page, below.

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

DELETE /cspace-services/accounts/{csid}/accountroles/{accountrolecsid} HTTP/1.1

AccountRole REST payload schemas

AccountRole instance schema

Create should use the following schema.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:account_role xmlns:ns2="http://collectionspace.org/services/authorization">
    <account>
      <accountId>311e3301-9789-45d8-9422-e209eb83dd3d</accountId>
      <screenName>acc-role-user1</screenName>
      <userId>acc-role-user1</userId>
    </account>
    <role>
      <roleId>69343d54-a8b9-4617-8c79-921cad0ddd64</roleId>
      <roleName>ROLE_CO2</roleName>
    </role>
    <role>
      <roleId>3534661b-4f06-4750-97a5-bab161e0db3a</roleId>
      <roleName>ROLE_CO1</roleName>
    </role>
</ns2:account_role>

Read will return the above.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:account_role xmlns:ns2="http://collectionspace.org/services/authorization">
    <account>
      <accountId>311e3301-9789-45d8-9422-e209eb83dd3d</accountId>
      <screenName>acc-role-user1</screenName>
      <userId>acc-role-user1</userId>
    </account>
    <role>
      <roleId>3534661b-4f06-4750-97a5-bab161e0db3a</roleId>
      <roleName>ROLE_CO1</roleName>
    </role>
    <role>
      <roleId>69343d54-a8b9-4617-8c79-921cad0ddd64</roleId>
      <roleName>ROLE_CO2</roleName>
    </role>
 </ns2:account_role>