Groups : Swarm Groups
Get List of Groups
Summary
Get List of Groups
GET /api/v9/groups/
Description
Returns the complete list of groups in Swarm.
Parameters
Parameter | Description | Type | Parameter Type | Required | Default Value |
---|---|---|---|---|---|
|
A group ID to seek to. Groups prior to and including the specified ID are excluded from the results and do not count towards |
string |
query |
No |
|
|
Maximum number of groups to return. This does not guarantee that |
integer |
query |
No |
100 |
|
An optional comma-separated list (or array) of fields to show for each group. Omitting this parameter or passing an empty value shows all fields. |
string |
query |
No |
|
|
Keywords to limit groups on. Only groups where the group ID, group name (if set), or description contain the specified keywords are returned. |
string |
query |
No |
|
|
Determines if the list of groups has the groupsBlacklist filter applied or not. Add the parameter to ignore the groupsBlacklist filter. |
boolean |
query |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"groups": [
{
"Group": "test-group",
"MaxLockTime": null,
"MaxResults": null,
"MaxScanRows": null,
"Owners": [],
"PasswordTimeout": null,
"Subgroups": [],
"Timeout": 43200,
"Users": ["bruno"],
"config": {
"description": "Our testing group",
"emailAddress": "test-group3@host.domain",
"emailFlags": [],
"name": "Test Group",
"useMailingList": true
}
}
]
}
Examples of usage
Listing groups
To list groups:
curl -u "username:password" \
"https://myswarm.url/api/v9/groups?keywords=test-group&fields=Group,Owners,Users,config&max=2"
Swarm responds with a list of groups:
{
"groups": [
{
"Group": "test-group",
"Owners": [],
"Users": ["bruno"],
"config": {
"description": "Our testing group",
"emailAddress": "test-group@host.domain",
"emailFlags": {
"reviews": "1",
"commits": "0"
},
"name": "Test Group",
"useMailingList: true
}
},
{
"Group": "test-group2",
"Owners": [],
"Users": ["bruno"],
"config": {
"description": "Our second testing group",
"emailAddress": "test-group2@host.domain",
"emailFlags": [],
"name": "Test Group 2",
"useMailingList: true
}
}
],
"lastSeen": "test-group2"
}
Paginating the groups list
Based on the previous example, we can pass a lastSeen value of test-group2
to see if there are any subsequent
groups in Swarm.
curl -u "username:password" \
"https://myswarm.url/api/v9/groups?keywords=test-group&fields=Group,config&max=2&lastSeen=test-group2"
Swarm responds with a list of groups (minus the Owners and Users fields, as we haven’t requested them):
{
"groups": [
{
"Group": "test-group3",
"config": {
"description": "Our 3rd testing group",
"emailAddress": "test-group3@host.domain",
"emailFlags": [],
"name": "Test Group 3",
"useMailingList": true
}
}
],
"lastSeen": "test-group3"
}
Get Group Information
Summary
Get Group Information
GET /api/v9/groups/{id}
Description
Retrieve information about a group.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
Group ID |
string |
path |
Yes |
|
An optional comma-separated list (or array) of fields to show for each group. Omitting this parameter or passing an empty value shows all fields. |
string |
query |
No |
|
Determines if the groupsBlacklist filter is applied or not when getting the group information. If the filter is applied and the group specified is present in the groupsBlacklist the group information is not included in the response. Add the parameter to ignore the groupsBlacklist filter. |
boolean |
query |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"group": {
"Group": "test-group",
"MaxLockTime": null,
"MaxResults": null,
"MaxScanRows": null,
"Owners": [],
"PasswordTimeout": null,
"Subgroups": [],
"Timeout": 43200,
"Users": ["bruno"],
"config": {
"description": "Our testing group",
"emailFlags": [],
"name": "Test Group"
}
}
}
Examples of usage
Fetching a group
To fetch an individual group:
curl -u "username:password" "https://myswarm.url/api/v9/groups/my-group"
Swarm responds with the group entity:
{
"group": {
"Group": "test-group",
"LdapConfig": null,
"LdapSearchQuery": null,
"LdapUserAttribute": null,
"MaxLockTime": null,
"MaxResults": null,
"MaxScanRows": null,
"Owners": [],
"Users": ["bruno"],
"config": {
"description": "Our testing group",
"emailAddress": "test-group@host.domain",
"emailFlags": {
"reviews": "1",
"commits": "0"
},
"name": "Test Group",
"useMailingList": true
}
}
}
Limiting returned fields
To limit the returned fields when fetching an individual group:
curl -u "username:password" "https://myswarm.url/api/v9/groups/my-group?fields=Group,Owners,Users,config"
Swarm responds with the group entity:
{
"group": {
"Group": "test-group",
"Owners": [],
"Users": ["bruno"],
"config": {
"description": "Our testing group",
"emailFlags": [],
"name": "Test Group"
}
}
}
Create a new Group
Summary
Create a new Group
POST /api/v9/groups/
Description
Creates a new group in Swarm.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
Group identifier string. |
string |
form |
Yes |
|
An optional array of group users. *At least one of Users, Owners, or Subgroups is required. |
array |
form |
No *See Description |
|
An optional array of group owners. *At least one of Users, Owners, or Subgroups is required. |
array |
form |
No *See Description |
|
An optional array of subgroups. *At least one of Users, Owners, or Subgroups is required. |
array |
form |
No *See Description |
|
An optional full name for the group. |
string |
form |
No |
|
An optional group description. |
string |
form |
No |
|
The email address for this group. |
string |
form |
No |
|
Email members when a new review is requested. |
boolean |
form |
No |
|
Email members when a change is committed. |
boolean |
form |
No |
|
Whether to use the configured email address or expand individual members addresses. |
boolean |
form |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"group": {
"Group": "test-group",
"MaxLockTime": null,
"MaxResults": null,
"MaxScanRows": null,
"Owners": [],
"PasswordTimeout": null,
"Subgroups": [],
"Timeout": null,
"Users": ["alice"],
"config": {
"description": "Test test test",
"emailAddress": "test-group@host.domain",
"emailFlags": [],
"name": "TestGroup",
"useMailingList": true
}
}
}
Example of usage
Create a group
- Only users with super privileges in the Helix Core server (
p4d
), or users with admin privileges inp4d
versions 2012.1 or newer, can create groups. - This API version is only capable of setting specific fields:
Group
,Users
,Owners
,Subgroups
,config
. Any other fields specified in the creation request are ignored.
To create a new group:
curl -u "username:password" \
-d "Group=my-group" \
-d "Owners[]=alice" \
-d "Owners[]=bob" \
-d "Users[]=bruno" \
-d "Users[]=user2" \
-d "config[description]=This group is special to me." \
-d "config[name]=My Group" \
-d "config[emailFlags][reviews]=1" \
-d "config[emailFlags][commits]=0" \
-d "config[emailAddress]=my-group@host.domain" \
-d "config[useMailingList]=false" \
"https://myswarm.url/api/v9/groups"
Assuming that the authenticated user has permission, Swarm responds with the new group entity:
{
"group": {
"Group": "my-group",
"MaxLockTime": null,
"MaxResults": null,
"MaxScanRows": null,
"Owners": ["username"],
"PasswordTimeout": null,
"Subgroups": [],
"Timeout": null,
"Users": [],
"config": {
"description": "This group is special to me.",
"emailFlags": {
"reviews": "1",
"commits": "0"
},
"name": "My Group",
"useMailingList": true
}
}
}
Edit a Group
Summary
Edit a Group
PATCH /api/v9/groups/{id}
Description
Change the settings of a group in Swarm. Only super users and group owners can perform this action.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
Group ID |
string |
path |
Yes |
|
An optional array of group users. |
array |
form |
No |
|
An optional array of group owners. |
array |
form |
No |
|
An optional array of group subgroups. |
array |
form |
No |
|
An optional full name for the group. |
string |
form |
No |
|
An optional group description. |
string |
form |
No |
|
The email address for this group. |
string |
form |
No |
|
Email members when a change is committed. |
boolean |
form |
No |
|
Email members when a new review is requested. |
boolean |
form |
No |
|
Whether to use the configured email address or expand individual members addresses. |
boolean |
form |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"group": {
"Group": "test-group",
"Users": [],
"Owners": [],
"Subgroups": [],
"config": {
"description": "New Group Description",
"name": "TestGroup",
"useMailingList": true
}
}
}
Example of usage
Editing a group
- Only users with super privileges in the Helix Core server, or group owners, can edit groups.
- This API version is only capable of modifying specific fields:
Users
,Owners
,Subgroups
,config
. Any other fields specified in the edit request are ignored.
Here is how to update the name
, description
, and emailFlags
configuration of the group my-group
:
curl -u "username:password" -X PATCH \
-d "config[description]=This group is special to me." \
-d "config[name]=My Group" \
-d "config[emailFlags][commits]=1" \
"https://myswarm.url/api/v9/groups/my-group"
Assuming that the authenticated user has permission, Swarm responds with the modified group entity:
{
"group": {
"Group": "my-group",
"Users": [],
"Owners": [],
"Subgroups": [],
"config": {
"description": "This group is special to me.",
"emailAddress": "test-group@host.domain",
"emailFlags": {
"reviews": "1",
"commits": "1"
},
"name": "My Group",
"useMailingList": true
}
}
}
Delete a Group
Summary
Delete a Group
DELETE /api/v9/groups/{id}
Description
Delete a group. Only super users and group owners can perform this action.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
Group ID. |
string |
path |
Yes |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"id": "test-group"
}
Example of usage
Deleting a group
Only super users and group owners can delete groups.
curl -u "username:password" -X DELETE "https://myswarm.url/api/v9/groups/my-group"
Assuming that the authenticated user has permission, Swarm
responds with the id
of the deleted group:
{
"id": "my-group"
}
Your search for returned result(s).