Remove content from catalogs: Migration guide

This guide outlines the main differences between the Remove content from catalogs v2 endpoint and the v1 deleteFromGroupCatalog 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.
• 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:

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

Behavior changes

This section details the specific changes in the internal behavior of the API.

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

Input changes

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

API v1 input example

curl --location -g --request DELETE 'https://{{host}}/api/v1/groups/5ae6f360c3b99d7884975380/catalog?company={{company}}&apiKey={{apiKey}}' \
--data-urlencode 'courses%5B0%5D=586d1323bc4937445ed96c37' \
--data-urlencode 'pathSessions%5B1%5D=596e151663b0c99f03a3e049'

API v2 input example

curl --request DELETE \
     --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": [
    {
      "contentType": "course",
      "contentId": "586d1323bc4937445ed96c37",
      "groupId": "5ae6f360c3b99d7884975380"
    },
    {
 			"contentType": "path-session",
      "groupId": "5ae6f360c3b99d7884975380",
      "contentId": "596e151663b0c99f03a3e049"
    }
  ]
}
'

Main input differences

Output changes

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

API v1 output example

The response is an empty body, indicated by the 204 status code.

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 (204 No Content) to asynchronous operations (202 Accepted). The primary change is the response code and the inclusion of the Location header to track the operation's status.