Public REST API
- Denny Miller
- Andy Brook [Plugin People]
Since v3.1.4, CSUM provides the option to hook into Public API REST Resources and Components, allowing 3rd party Developers to externally perform CSUM operations outside of the app.
Public Endpoints
You will need to perform these requests as the logged in user that has authorisation to the specific operation.
For example, using a curl command will require the -u username:password to authenticate.
Create Space Group
Allows the creation of a new Space Group using the provided groupName with the provided spaceKey.
Endpoint |
|---|
|
Params
QueryParam Name | Description |
|---|---|
| The SpaceKey of the Space the group should be created in and given the SpaceGroupPattern prefix/suffix from. |
| The name of the new Group to be created. This should contain the spaceKey suffix/prefix |
SpaceGroupPattern is applied on this operation, for example:
#Example curl request using basic auth on a confluence debug instance
curl -u admin:admin -X POST -H 'Content-Type: application/json' "http://localhost:1990/confluence/rest/csum/latest/public/group/create?spaceKey=TESTSPACE&groupName=new-group
# This creates a new group "testspace-new-group" if the SpaceGroupPattern prefix is set. Response
Returns the status code of the request if authentication is valid, else a 401 response page from Atlassian will be returned (which is not an int).
Response Type: int | Status Type | Description |
|---|---|---|
200 | OK | Group Created successfully. |
400 | Bad Request | This can occur due to invalid Licensing or invalid SpaceKey provided. |
409 | Conflict | This can occur if a group creation attempts to create a group with the same name as an existing space group. |
Delete Space Group
Allows the deletion of an existing Space Group using the provided groupName with the provided spaceKey.
Endpoint |
|---|
|
Params
QueryParam Name | Description |
|---|---|
| The SpaceKey of the Space the group should be deleted from. |
| The name of the Group to be deleted. This should contain the spaceKey suffix/prefix |
SpaceGroupPattern is applied on this operation, for example:
#Example curl request using basic auth on a confluence debug instance
curl -u admin:admin -X DELETE -H 'Content-Type: application/json' "http://localhost:1990/confluence/rest/csum/latest/public/group/delete?spaceKey=TESTSPACE&groupName=new-group
# This deletes the group "testspace-new-group" if the SpaceGroupPattern prefix is set. Response
Returns the status code of the request if authentication is valid, else a 401 response page from Atlassian will be returned (which is not an int).
Response Type: int | Status Type | Description |
|---|---|---|
200 | OK | Group Deleted successfully. |
400 | Bad Request | This can occur due to invalid Licensing or invalid SpaceKey provided. |
409 | Conflict | This can occur if a group creation attempts to create a group with the same name as an existing space group. |
Add Group Members
Allows the addition of Users and Group Members to the provided SpaceGroups.
Endpoint |
|---|
|
Params
QueryParam Name | Description |
|---|---|
| The SpaceKey of the Space to operate against. |
| CSV Split values of the SpaceGroup names you want to add members to |
| CSV split usernames of users you want to add to the groups found in |
| CSV split GroupNames of Groups. All members in these groups will be added into the groups from |
#Example curl request using basic auth on a debug confluence instance
curl -u admin:admin -X PUT -H 'Content-Type: application/json' "http://localhost:1990/confluence/rest/csum/latest/public/group/addusers?spaceKey=TEST&spaceGroups=test-newgroupname&spaceUsers=admin
# This adds the user "admin" into the group "test-newgroupname" if valid. Response
Returns the Response of failed users. If all is successful, {} should be returned.
Response: | Status Type | Description |
|---|---|---|
| OK | Members added to group without error. |
| All invalid users | If the user value is invalid/user could not be found, they will return with an ‘invalid’ value. |
| All users with membership | If a user is attempted to be added to the provided groups but already has membership, they will return with a ‘membership’ value. |
Remove Group Members
Allows the removal of Users and Group Members to the provided SpaceGroups.
Endpoint |
|---|
|
Params
QueryParam Name | Description |
|---|---|
| The SpaceKey of the Space to operate against. |
| CSV Split values of the SpaceGroup names you want to remove members from. |
| CSV split usernames of users you want to remove from the groups found in |
| CSV split GroupNames of Groups. All members in these groups will be removed from the groups from |
Response
Returns the Response of the operation. If all is successful, no value is returned.
Response: | Status Type | Description |
|---|---|---|
<No Value> | OK | Members removed from group without error. |
| Invalid SpaceKey | If the SpaceKey value provided is returned, it is not a valid SpaceKey. |
| Invalid / No Groups Provided | If |
Add Delegated Group Members
Allows the addition of Users and Group Members to the provided Delegated Groups.
Endpoint |
|---|
|
Params
QueryParam Name | Description |
|---|---|
| The SpaceKey of the Space to operate against. |
| CSV Split values of the Delegated Group names you want to add members to |
| CSV split usernames of users you want to add to the groups found in |
| CSV split GroupNames of Groups. All members in these groups will be added into the groups from |
Response
Returns JSONAddUserResultBean[]. Example Response and Bean values are listed below.
Response: | Status Type | Description |
|---|---|---|
| Example Bean Response | Bean response for each ‘add’ operation on |
Remove Delegated Group Members
Allows the removal of Users and Group Members to the provided Delegated Groups.
Endpoint |
|---|
|
Params
QueryParam Name | Description |
|---|---|
| The SpaceKey of the Space to operate against. |
| CSV Split values of the SpaceGroup names you want to remove members from. |
| CSV split usernames of users you want to remove from the groups found in |
| CSV split GroupNames of Groups. All members in these groups will be removed from the groups from |
Response
Returns the Response of the operation. If all is successful, [] (Empty Array) is returned.
Response: | Status Type | Description |
|---|---|---|
| OK | Members removed from group without error. |
| Invalid Users provided | If |
Retrieve Audit Entries
Allows the retrieval of Audit Entries with pagination and offset limits.
Endpoint |
|---|
|
Params
QueryParam Name | Description |
|---|---|
| The draw counter for calling audit event retrieval. The most recent (largest value) draw is returned |
| The entry ID start point |
| The total number of audit entries to retrieve (E.g. length=10 will return max 10 results) |
| The column to be ordered against matching the In-App table (int) |
| The direction of audit entries ("asc"/"desc") |
| success / error / unauthorized |
| The Context Group that was Operated on |
| The Context User that was Operated on |
| The space to retrieve audit entries for |
Response
Returns the JSON response of the Audit entries found matching the given criteria.
Public Component Classes
The following Interfaces are exposed to perform the same functionality as above. These Classes can be used internally within your code to hook into CSUM’s operations.
IPublicCSUMSpaceGroupManager
Method Name | Description | Returns |
|---|---|---|
| Allows SpaceGroup creation |
The Group created. |
| Allows SpaceGroup deletion |
Boolean value of if Group was deleted successfully or not. |
| Allows Group Membership addition |
Left List returns failed Users, Right List returns invalid Groups. |
| Allows Group Membership removal |
|
Example:
IPublicCSUMDlgSpaceGroupManager
Method Name | Description | Returns |
|---|---|---|
| Allows Group Membership addition for Authorized Delegated Space Groups |
Response Bean of operation info (Success total, failed users, etc) |
| Allows Group Membership removal for Authorized Delegated Space Groups |
List of failed users |
Example: