Create a group: Migration guide

This guide outlines the changes introduced in the Create a group v2 endpoint (formerly createGroup in API v1).

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
• API v2: /api/v2/groups

Behavior changes (if applicable)

API v2 returns a 201 status code upon successful group creation, along with the details of the created group in the response body. v1 returned a 200 status with a JSON body containing a status message and the group ID.

Input changes

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

API v1 input example

Shell

curl --location 'https://app.360learning.com/api/v1/groups?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name=Engineering Team' \
--data-urlencode 'public=true' \
--data-urlencode 'custom=Unit 101' \
--data-urlencode 'parent=507f1f77bcf86cd799439011' \
--data-urlencode 'bannerImageId=567b608aaa92bb411526b31a'

API v2 input example

Shell

curl --request POST \
     --url https://app.360learning.com/api/v2/groups \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "public": true,
  "parentId": "507f1f77bcf86cd799439011",
  "name": "Engineering Team",
  "custom": "Unit 101"
}
'

Main input differences

Change type	API v1	API v2
Removed Body parameter	bannerImageId (Optional): Removed from endpoint v2 version, not replaced.	-
Modified Body parameter	parent: The unique ID of the parent group.	parentId: The unique ID of the parent group, renamed.

Output changes

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

API v1 output example

JSON

{
  "status": "group_created",
  "id": "596f7256b6afcb59a2dd60ef"
}

API v2 output example

JSON

{
  "public": true,
  "parentId": "507f1f77bcf86cd799439011",
  "_id": "507f1f77bcf86cd799439011",
  "name": "Engineering Team",
  "custom": "Unit 101"
}

Main output differences

API v2 provides a more detailed and standardized response upon successful creation, including the full representation of the created group.

Change type	API v1	API v2
Removed Output property	status: A string indicating the creation status (e.g., group_created).	-
Modified Output property	id: The unique ID of the group.	_id: Renamed.
Modified Success output	200: Returns a JSON object with a status and id upon successful creation.	201: Returns the full JSON representation of the newly created group in the response body.
Added Output property	-	public: Indicates if the group is public or private.
Added Output property	-	parentId: The unique ID of the parent group.
Added Output property	-	_id: The unique ID of the group.
Added Output property	-	name: The name of the group.
Added Output property	-	custom: A custom field to store information.