Groups: Swarm groups

Get a list of groups

Summary

Get a list of groups.

GET /api/v11/groups

Description

Get a list of groups.

Parameters

Parameter	Description	Type	Parameter Type	Required
[ids]	An optional array of group ids to return in the response. Omitting this parameter or passing an empty value shows all groups.	string	query	No
[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
[expand]	An optional parameter to specify whether details of any subgroups in a group are returned in the response. Omitting the expand parameter or passing an empty value will not return subgroup details. true: Returns details of any subgroups for each group returned. This is done recursively, so if a subgroup has a subgroup, its details are also returned. false: Details of any subgroups in the groups are not returned.	boolean	query	No

Example usage

Get a list of all groups

curl -u "username:ticket" "https://myswarm-url/api/v11/groups"

Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "groups": [
      {
        "id": "Mercury",
        "description": "Group for project Mercury that includes Development, QA, and Docs",
        "maxResults": null,
        "maxScanRows": null,
        "maxLockTime": null,
        "maxOpenFiles": "unset",
        "timeout": 43200,
        "passwordTimeout": null,
        "ldapConfig": null,
        "ldapSearchQuery": null,
        "ldapUserAttribute": null,
        "subgroups": [
          "mercury-dev",
          "mercury-docs",
          "mercury-qa"
        ],
        "owners": [
          "allison.clayborne",
          "jack.boone"
        ],
        "users": [
          "allison.clayborne",
          "jack.boone",
          "claire.brevia",
          "alex.randolph"
        ],
        "name": "Mercury",
        "emailFlags": [],
        "group_notification_settings": null,
        "emailAddress": null,
        "useMailingList": "mercury.group@nowhere.xxjzzj.com"
      },
      {
      ...
      <Other group ids formatted as above>
      ...
      }
    ]
  }
}

Limiting returned fields

To limit the returned fields when fetching groups:

curl -u "username:ticket" "https://myswarm-url/api/v11/groups?fields=id,owners,users"

Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "groups": [
      {
        "id": "Mercury",
        ],
        "owners": [
          "allison.clayborne",
          "jack.boone"
        ],
        "users": [
          "allison.clayborne",
          "jack.boone",
          "claire.brevia",
          "alex.randolph"
        ],
      },
      {
      ...
      <Other group ids formatted as above>
      ...
      }
    ]
  }
}

Limiting groups returned and expanding subgroup details

Return the id, name, and subgroups fields for the Mercury group and return subgroup details:

curl -u "username:ticket" "https://myswarm-url/api/v11/groups?fields=id,name,subgroups&ids=Mercury&expand=true"

Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "groups": [
      {
        "id": "Mercury",
        "name": "Mercury",
        "subgroups": [
          "mercury-dev",
          "mercury-docs",
          "mercury-qa"
        ]
      },
        "id": "mercury-dev",
        "name": "mercury-dev",
        "subgroups": []
      },
      {
        "id": "mercury-docs",
        "name": "mercury-docs",
        "subgroups": []
      },
      {
        "id": "mercury-qa",
        "name": "mercury-qa",
        "subgroups": []
      }
    ]
  }
}