Group Service RESTful APIs - Release v1.8

Owned by Adaptavist ScriptRunner for Confluence Cloud
Dec 19, 2022
2 min read
Group Service Home

Brief Description

Error rendering macro 'excerpt-include' : No link could be created for 'DOC:Generic Group Service Description and Assumptions'.
For a full description, visit the Service Description and Assumptions page.

Assumptions

For a complete list of assumptions, visit the Service Description and Assumptions page.

References

Group User Story Summary
Generic Group Service Description and Assumptions
Group Schema

REST-based API

To obtain a list of items in a group, use the Relations Service to obtain a list of items that are related to that group, via the CollectionSpace ID (CSID) of the group record.

The Group Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual Group instances, plus list operations on multiple Group instances. These follow the Common model for CollectionSpace REST services.

Group CRUD+L services

Create a Group

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

POST /cspace-services/groups HTTP/1.1
Read a Group

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

GET /cspace-services/groups/{id} HTTP/1.1
Update an Group

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

PUT /cspace-services/groups/{id} HTTP/1.1
Delete a Group

Deletes an existing Group record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

DELETE /cspace-services/groups/{id} HTTP/1.1
List Group instances

Lists existing Group records, with summary information for each. Follows standard List model. See the documentation of the Group list schema, below. Example:

GET /cspace-services/groups/ HTTP/1.1

Group REST payload schemas

Group instance schema

The schemas below are illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Group records, please see the Group record schema for the current release.

Create and Update should use the following schema:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="groups">
	<ns2:groups_common xmlns:ns2="http://collectionspace.org/services/group" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<title>Test Group</title>
		<scopeNote>This is just for testing</scopeNote>
		<responsibleDepartment>antiquities</responsibleDepartment>
		<owner>urn:cspace:org.collectionspace.demo:personauthority:id(497bd6eb-6093-4644-b7e4):person:id(eb8a3dcb-0bed-435f-a4e1)'Patrick+Stewart'</owner>
	</ns2:groups_common>
	<ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<tenantId>1</tenantId>
		<updatedAt>2011-05-19T17:20:56Z</updatedAt>
		<createdAt>2011-05-19T17:20:56Z</createdAt>
	</ns2:collectionspace_core>
	<ns2:account_permission xmlns:ns2="http://collectionspace.org/services/authorization">
		...
	</ns2:account_permission>
</document>
Group list schema

Group uses the new abstract common list mechanism, allowing for some configuration of returned fields. By default, List (and variants) will return the following schema. This schema includes the uri and csid fields to help facilitate access to individual records:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:abstract-common-list xmlns:ns2="http://collectionspace.org/services/jaxb">
	<pageNum>0</pageNum>
	<pageSize>40</pageSize>
	<itemsInPage>1</itemsInPage>
	<totalItems>1</totalItems>
	<fieldsReturned>csid|uri|title</fieldsReturned>
	<list-item>
		<csid>05e5c5cf-faad-427c-8220</csid>
		<uri>/groups/05e5c5cf-faad-427c-8220</uri>
		<title>Test Group</title>
	</list-item>
</ns2:abstract-common-list>