Groups : Swarm Groups

From Swarm 2022.2, Swarm no longer supports APIs older than v9.

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

after

A group ID to seek to. Groups prior to and including the specified ID are excluded from the results and do not count towards max. Useful for pagination. Commonly set to the lastSeen property from a previous query.

string

query

No

 

max

Maximum number of groups to return. This does not guarantee that max groups are returned. It does guarantee that the number of groups returned won’t exceed max.

integer

query

No

100

fields

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

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

 

ignoreExcludeList

Determines if the list of groups has the group_exclude_list filter applied or not. Add the parameter to ignore the group_exclude_list 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:

HTTP/1.1 200 OK

{
  "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):

HTTP/1.1 200 OK

{
  "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

id

Group ID

string

path

Yes

fields

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

ignoreExcludeList

Determines if the group_exclude_list filter is applied or not when getting the group information. If the filter is applied and the group specified is present in the group_exclude_list the group information is not included in the response. Add the parameter to ignore the group_exclude_list 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:

HTTP/1.1 200 OK

{
  "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:

HTTP/1.1 200 OK

{
  "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

Group identifier string.

string

form

Yes

Users

An optional array of group users.

*At least one of Users, Owners, or Subgroups is required.

array

form

No

*See Description

Owners

An optional array of group owners.

*At least one of Users, Owners, or Subgroups is required.

array

form

No

*See Description

Subgroups

An optional array of subgroups.

*At least one of Users, Owners, or Subgroups is required.

array

form

No

*See Description

config[name]

An optional full name for the group.

string

form

No

config[description]

An optional group description.

string

form

No

config[emailAddress]

The email address for this group.

string

form

No

config[emailFlags][reviews]

Email members when a new review is requested.

boolean

form

No

config[emailFlags][commits]

Email members when a change is committed.

boolean

form

No

config[useMailingList]

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 in p4d 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" \
     -X POST \
     -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:

HTTP/1.1 200 OK

{
  "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

id

Group ID

string

path

Yes

Users

An optional array of group users.

array

form

No

Owners

An optional array of group owners.

array

form

No

Subgroups

An optional array of group subgroups.

array

form

No

config[name]

An optional full name for the group.

string

form

No

config[description]

An optional group description.

string

form

No

config[emailAddress]

The email address for this group.

string

form

No

config[emailFlags][commits]

Email members when a change is committed.

boolean

form

No

config[emailFlags][reviews]

Email members when a new review is requested.

boolean

form

No

config[useMailingList]

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:

HTTP/1.1 200 OK

{
  "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

id

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:

HTTP/1.1 200 OK

{
  "id": "my-group"
}