Retrieve a group: Migration guide

This guide details how to migrate from the v1 group retrieval endpoints (GET /api/v1/groups/:group_id and HEAD /api/v1/groups/:group_id) to the new v2 Retrieve a group endpoint.

💡

Key changes

Split functionality: Functionality of the v1 getGroup endpoint is now split.

• This v2 endpoint focuses on retrieving core group details.
• User details are now retrieved via a separate List all memberships in a group endpoint, which is a paginated endpoint.

Documentation links

Here are the links to the API reference for:

• API v1
• API v2

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}

Behavior changes

You can continue to use the HEAD method to check for a group's existence without retrieving a response body.

For GET requests, the v2 endpoint no longer returns lists of members (users, coaches, admins, authors) within the group object. The response is now focused exclusively on the group's metadata. The list of members can be retrieved via List all memberships in a group.

Input

This section details the specific alterations to the input requirements between API versions.

API v1 input example

HEAD request

curl --location --head 'https://app.360learning.com/api/v1/groups/567b608a1a92bb4fb526b31a?company=6470744ad045da027bccafcf&apiKey=5fa7653c2dc94426b3eb8c2a26cbcc6d

GET request

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

API v2 input example

HEAD request

curl --location --head 'app.360learning.com/api/v2/groups/567b608a1a92bb4fb526b31a' \
--header '360-api-version: v2.0' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_access_token'

GET request

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

Main input differences

For both HEAD and GET requests:

Output changes

The response to a HEAD request remains a body-less success status in both versions.

The following changes apply to the response body of a GET request.

API v1 output example

{
    "_id": "567b608a1a92bb4fb526b31a",
    "admins": [
        {
            "_id": "67769f32553f1e9171a186c0",
            "mail": "[email protected]"
        }
    ],
    "authors": [
        {
            "_id": "6776a60b590663fc1a82eaac",
            "mail": "[email protected]"
        }
    ],
    "coaches": [
        {
            "_id": "6776a6558d12670efdcb2ed8",
            "mail": "[email protected]"
        }
    ],
    "name": "Group 1.1",
    "parent": "66191d36e4c25b72bccc7312",
    "userAdmins": [
        {
            "_id": "6776a6558d12670efdcb2ed8",
            "mail": "[email protected]"
        }
    ],
    "users": [
        {
            "_id": "6776a5bec15cfced511e7bc4",
            "mail": "[email protected]"
        }
    ],
    "public": true
}

API v2 output example

{
  "_id": "567b608a1a92bb4fb526b31a",
  "parentId": "66191d36e4c25b72bccc7312",
  "public": true,
  "name": "Group 1.1"
}

Main output differences

For the GET request, API v2 provides a more streamlined response, focusing on the essential properties of a group.

The user details (admins, authors, coaches, users) are no longer directly embedded in the response. Use List all memberships in a group to retrieve detailed information about the users associated with the group.