Archive external courses: Migration guide

This guide details how the Archive external courses endpoint replaces the deleteExternalCourses endpoint in v1.

💡

Key changes

• Restricted scope: The v2 endpoint is restricted and requires the following scope: integrations: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.

Documentation links

• API v1
• API v2

Endpoint mapping

• API v1: /api/v1/externalContents/groups/:groupId/externalPlatforms/:externalPlatform/courses
• API v2: /api/v2/bulk/integrations/{integrationId}/courses

Behavior changes

• 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 includes a Location header to track the bulk operation's status.
• Bulk scope: The v2 endpoint is designed for high-volume archiving, allowing the removal of up to 1,000 external courses linked to a specific integration in a single asynchronous call.

Input changes

 API v1 input example

curl --location -g --request DELETE 'https://app.360learning.com/api/v1/externalContents/groups/:groupId/externalPlatforms/:externalPlatform/courses' \
--header 'Content-Type: application/json' \
--data '{
    "externalIds": ["l3ssup3rh3r0s"]
}'

API v2 input example

curl --request DELETE \
     --url https://app.360learning.com/api/v2/bulk/integrations/507f1f77bcf86cd799439011/courses \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer your_access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "input": [
    {
      "externalId": "l3ssup3rh3r0s"
    }
  ]
}
'

Main input differences

Output changes

API v1 output example

{
  "totalCoursesArchived": 1,
  "totalArchiveErrors": 0,
  "externalCoursesStatus": [
    {
      "externalId": "l3ssup3rh3r0s",
      "status": 204,
      "message": "External course archived"
    }
  ]
}

 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 (200 OK) 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.