Migrate addToGroupCatalog

This guide outlines the main differences between the Add content to catalogs v2 endpoint and the v1 addToGroupCatalog endpoint.

💡
Key changes

Restricted scope: The v2 endpoint is restricted and requires the following scope: groups:bulk. To request this scope, reach out to your Customer Success Partner (CSP).

Bulk operation: The v2 endpoint operates as a bulk endpoint, allowing you to process up to 20,000 objects asynchronously. The v1 endpoint was a synchronous operation for a single group.

HTTP method: The v2 endpoint uses the POST method, while v1 used the PUT method.

Request structure: The v2 endpoint requires a JSON request body, replacing the URL-encoded form data used in v1.

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

Behavior changes

Bulk operation: The v2 endpoint is designed for bulk addition, allowing multiple group/content associations across different groups and content types in a single call (up to 20,000 items). The v1 endpoint only supported adding content to a single group per request.
Asynchronous processing: API v2 shifts from synchronous to asynchronous operations. Instead of an immediate success (200 OK), it returns a 202 Accepted status code. The response will include a Location header with a URL to track the bulk operation's status.

Input changes

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

API v1 input example

curl --location -g --request PUT 'https://app.360learning.com/api/v1/groups/567b608a1a92bb4fb526b31a/catalog' \
--data-urlencode 'courses%5B0%5D=867b608a1a92bb4fb526b31a'

API v2 input example

curl --request POST \
     --url https://app.360learning.com/api/v2/bulk/groups/catalog \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer your_access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "input": [
    {
      "groupId": "507f1f77bcf86cd799439011",
      "contentId": "507f1f77bcf86cd799439011",
      "contentType": "path-session"

    },
    {
      "groupId": "507f1f77bcf86cd799439011",
      "contentId": "507f1f77bcf86cd799439011",
      "contentType": "course"
    }
  ]
}
'

Main input differences

Change type	API v1	API v2
Removed Path parameter	`group_id` (Required): The unique ID of the group.	Replaced by `groupId` body parameter.
Removed Body parameter	`programSessions[i]`: URL-encoded parameter containing a program session ID.	Removed because the underlying feature (Programs) has been retired from the platform and is not supported in API v2.
Removed Body parameter	`courses[i]`: URL-encoded parameter containing a course ID.	Content IDs and types are now specified using the nested fields `contentId` and `contentType`.
Removed Body parameter	`pathSessions[i]`: URL-encoded parameter containing a path session ID.	Content IDs and types are now specified using the nested fields `contentId` and `contentType`.
Added Header parameter		`360-api-version` (Required): API version identifier. Example: `v2.0`.
Added Body parameter		`input` (Required, length ≤ 20000): New array of objects for bulk processing.
Added Body parameter		`groupId` (Required, nested in input): The unique ID of the group. V1 used a path parameter.
Added Body parameter		`contentId` (Required, nested in input): The unique ID of the content. V1 used URL-encoded parameters.
Added Body parameter		`contentType` (Required, nested in input): The type of the content (`path-session`, `course`). V1 inferred type from parameter name.

Output changes

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

API v1 output example

{
    "status": "group_updated"
}

API v2 output example

No JSON body is returned for a successful submission. The 202 status code is the key response indicator.

Main output differences

API v2 shifted from synchronous to asynchronous operations. Instead of an immediate result (200 OK), it returns a 202 Accepted status code indicating the bulk request has been queued. The full result must be tracked via the Location header.

Change type	API v1	API v2
Removed Output property	`status`: Property confirming group update status (`group_updated`). Removed in v2 because the operation is asynchronous.
Modified Success output	`200`: Returns immediate success and status object.	`202 Accepted`: Changed for asynchronous operation tracking. The response includes a `Location` header to track bulk operation status.