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

Shell

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

GET request

Shell

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

API v2 input example

HEAD request

Shell

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

Shell

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:

Change type	API v1	API v2
Modified Path parameter	group_id (Required): The ID of the group.	groupId (Required): Renamed.

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

JSON

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

JSON

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

Change type	API v1	API v2
Removed Output property	admins: Removed from this endpoint v2.	Member details can be retrieved via a separate List all memberships in a group endpoint.
Removed Output property	authors: Removed from this endpoint v2.	Member details can be retrieved via a separate List all memberships in a group endpoint.
Removed Output property	coaches: Removed from this endpoint v2.	Member details can be retrieved via a separate List all memberships in a group endpoint.
Removed Output property	users: Removed from this endpoint v2.	Member details can be retrieved via a separate List all memberships in a group endpoint.
Removed Output property	userAdmins: Array of user admin objects within the group. Removed from the v2 response.	Member details can be retrieved via a separate List all memberships in a group endpoint.
Modified Output property	parent: The unique ID of the parent group.	parentId: Renamed.