List all memberships in a group: Migration guide

This guide details how the functionality of retrieving group members has changed. In v1, user details (admins, authors, coaches, users) were embedded within the getGroup endpoint. In v2, this information is now accessed through the List all memberships in a group endpoint.

💡
Key changes

Split functionality: The v1 getGroup endpoint's functionality is now split.

This List all memberships in a group v2 endpoint specifically focuses on listing the details of the group members.

Core group details are now retrieved via a separate Retrieve a group endpoint.

Pagination: This v2 endpoint is paginated, returning up to 1,000 memberships per page. You'll need to implement pagination handling to retrieve all members if a group has more than 1,000 members. Refer to the Pagination guide for more details.

Documentation links

Here are the links to the API reference for:

Endpoint mapping

Here's the direct correlation between the v1 and v2 endpoint URLs:

API v1: /api/v1/groups/:group_id
API v2: /api/v2/groups/{groupId}/roles

Behavior changes

The key behavior change is the separation of concerns. Instead of getting group details and member lists in one go, you now make a specific call to retrieve the member list. This allows for more efficient retrieval of member information when core group information is not immediately needed.

Input changes

There are no endpoint-specific input changes for this request. The group_id path parameter functions just as it did in v1, and there are no new query or body parameters to consider.

All input changes relate to the new authentication and versioning headers, which are detailed in our Authentication guide.

API v1 input example

curl --location 'https://app.360learning.com/api/v1/groups/567b608a1a92bb4fb526b31a?company={{company}}&apiKey={{apiKey}}'

API v2 input example

curl --request GET \
  --url https://app.360learning.com/api/v2/groups/567b608a1a92bb4fb526b31a/roles \
  --header '360-api-version: v2.0' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer access_token'

Output changes

This section details the specific alterations to the output returned between API versions.

API v1 output example

{
  "_id": "507f1f77bcf86cd799439011",
  "custom": "Unit 101",
  "name": "Engineering Team",
  "admins": [
    {
      "_id": "55a61fe1f3d39aaa14de320e",
      "mail": "[email protected]"
    }
  ],
  "authors": [
    {
      "_id": "55aaaae1f3d39eb914de320e",
      "mail": "[email protected]"
    },
    {
      "_id": "55a61f8df3d39eb111de31f6",
      "mail": "[email protected]"
    }
  ],
  "coaches": [
    {
      "_id": "596f383291524ee907bc36d5",
      "mail": "[email protected]"
    }
  ],
  "public": true,
  "users": [
    {
      "_id": "596f383291524ee907bc36d5",
      "mail": "[email protected]"
    },
    {
      "_id": "596f384acbb356e9a16190b4",
      "mail": "[email protected]"
    }
  ]
}

API v2 output example

[
  {
    "userId": "507f1f77bcf86cd799439011",
    "role": "admin"
  },
  {
    "userId": "612a8c7e9b8d3a4f2e1c5d67",
    "role": "learner"
  }
  // ... up to 1000 memberships
]

Main output differences

The v2 List all memberships in a group endpoint returns a flat array of membership objects. Each object specifies a userId and their corresponding role within the group. The email address of the user is not included in this response and would need to be fetched via a separate user retrieval endpoint, such as Retrieve a user or List all users.

Additionally, v2 introduces pagination via the Link header.

Change type	API v1	API v2
Removed Output property	`_id`: Removed from this v2 version.	Group core details can be retrieved via Retrieve a group.
Removed Output property	`name`: Removed from this v2 version.	Group core details can be retrieved via Retrieve a group.
Removed Output property	`custom`: Removed from this v2 version.	Group core details can be retrieved via Retrieve a group.
Removed Output property	`public`: Removed from this v2 version.	Group core details can be retrieved via Retrieve a group.
Removed Output property	`admin`: Array of objects containing admin user IDs and emails.	Membership information is now a flat array of `{userId, role}` objects. Emails can be fetched via Retrieve a user or List all users.
Removed Output property	`authors`: Array of objects containing author user IDs and emails.	Membership information is now a flat array of `{userId, role}` objects. Emails can be fetched via Retrieve a user or List all users.
Removed Output property	`coaches`: Array of objects containing coaches user IDs and emails.	Membership information is now a flat array of `{userId, role}` objects. Emails can be fetched via Retrieve a user or List all users.
Removed Output property	`users`: Array of objects containing user IDs and emails.	Membership information is now a flat array of `{userId, role}` objects. Emails can be fetched via Retrieve a user or List all users.
Removed Error code	`400`: Invalid input.	v2 provides more specific error codes like `401` (authentication), `404` (resource not found), and `403` (authorization/scope issues) to better indicate the nature of the problem.
Modified Success output	`200`: Returns the entire group object with embedded user arrays.	`200`: Returns one page of up to 1000 membership objects, and a `Link` header with the URL to fetch the next page of data.
Modified Error code	`401`: Used for various authentication issues and included potentially invalid group IDs.	`401`: Used for authentication errors. Invalid group IDs are now included in the `404` error code.
Added Error code	-	`403`: Invalid scope.
Added Error code	-	`404`The given `groupId` does not correspond to any existing group. Note: This specific error was previously often included within the `401` error in v1.
Added Output property	-	`userId`: String representing the unique ID of a user in the group.
Added Output property	-	`role`: String indicating the user's role in the group (`admin`, `author`, `coach`, `learner`, `owner`, `userAdmin`).
Added Header	-	`Link`: Header with the URL to fetch the next page of data.

💡Key changes