Retrieve an external course: Migration guide

This guide details how the Retrieve an external course endpoint replaces the v1 getExternalCourse using the external ID.

Documentation links

Endpoint mapping

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

Input changes

API v1

curl --location -g 'https://app.360learning.com/api/v1/externalContents/groups/62be0535045424d93edaad7b/externalPlatforms/myPlatform/courses/l3ssup3rh3r0s'

API v2

curl --request GET \
     --url https://app.360learning.com/api/v2/integrations/507f1f77bcf86cd799439011/courses/a3215H-7 \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer your_access_token'

Main input differences

Change type	API v1	API v2
Removed Path parameter	`groupId`	Replaced by: `integrationId`. A single unique ID now identifies the integration.
Removed Path parameter	`externalPlatform`	Replaced by: `integrationId`. A single unique ID now identifies the integration
Added Header		`360-api-version`: Required (e.g., `v2.0`).

Output changes

API v1

{
  "id": "6463973f9b19ff7b9ca674e9",
  "authorId": "62bdbc00293a604543f44386",
  "archived": false,
  "title": "Machine Learning Crash Course",
  "description": "Learn the basics of machine learning.",
  "language": "en",
  "courseDuration": 10,
  "skills": [
    "63970d8ec2675a57f2b3f509"
  ],
  "externalId": "l3ssup3rh3r0s",
  "externalPlatform": "myPlatform",
  "groupId": "62be0535045424d93edaad7b",
  "authors": [
    "John Doe"
  ],
  "alternativeLanguages": [
    "fr"
  ],
  "launchUrl": "https://player.mylearningplatform.com/ql/fg-q6dfax2e_6ys",
  "mobileLaunchUrl": "https://player.mylearningplatform.com/mobile/fg-q6dfax2e_6ys",
  "thumbnailUrl": "https://upload.wikimedia.org/wikipedia/commons/0/07/Wikipedia_logo_%28svg%29.svg",
  "difficultyLevel": "beginner",
  "contentType": "course",
  "numberOfVideos": 1,
  "sources": [
    {
      "name": "Wikipedia",
      "logo": "https://en.wikipedia.org/static/images/icons/wikipedia.png"
    }
  ],
  "subjects": [
    "Machine learning"
  ]
}

API v2

{
  "defaultLang": "bg",
  "externalId": "l3ssup3rh3r0s",
  "launchUrl": "https://player.mylearningplatform.com/launch/l3ssup3rh3r0s",
  "name": "Machine Learning Crash Course",
  "sources": [
    {
      "name": "Wikipedia",
      "logoUrl": "https://en.wikipedia.org/static/images/icons/wikipedia.png"
    }
  ],
  "subjects": [
    "Machine Learning",
    "IT"
  ],
  "contentType": "article",
  "description": "Learn the basics of machine learning.",
  "difficultyLevel": "advanced",
  "duration": 45,
  "imageUrl": "https://player.mylearningplatform.com/image/l3ssup3rh3r0s",
  "mobileLaunchUrl": "https://player.mylearningplatform.com/mobile/launch/l3ssup3rh3r0s",
  "authorId": "507f1f77bcf86cd799439011",
  "courseId": "507f1f77bcf86cd799439011",
  "translations": [
    {
      "lang": "fr",
      "translatedFields": {
        "description": "Apprenez les bases de l'apprentissage automatique.",
        "launchUrl": "https://player.mylearningplatform.com/launch/l3ssup3rh3r0s/fr",
        "mobileLaunchUrl": "https://player.mylearningplatform.com/mobile/launch/l3ssup3rh3r0s/fr",
        "name": "Cours intensif sur l'apprentissage automatique",
        "subjects": [
          "Apprentissage automatique",
          "TI"
        ]
      }
    }
  ]
}

Main output changes

Change type	API v1	API v2
Removed Output property	`archived`: Boolean (`true`/`false`).
Removed Output property	`authors`: Array of the authors of the external course.	Replaced by users' internal IDs in v2. Use Retrieve a user to get full users' information.
Removed Output property	`numberOfVideos`: The number of videos / activities in the external course.
Removed Output property	`skills`: Array of skill IDs.	Use List all tags in a course to get the list of tags (previously known as skills) associated with the course.
Modified Output property	`id`: Platform internal ID.	`courseId`: Renamed for clarity.
Modified Output property	`title`: Title of the course.	`name`: Renamed property.
Modified Output property	`courseDuration`: Duration in minutes.	`duration`: Renamed property.
Modified Output property	`thumbnailUrl`: Image URL.	`imageUrl`: Renamed property.
Modified Output property	`language`: Main default language of the external course	`defaultLang:` Renamed property.
Modified Output property	`logo`: URL of source logo.	`logoUrl`: Nested in sources object and renamed.
Modified Output property	`alternativeLanguages`: String array.	`translations`: Array of objects containing `langs` and `translatedFields`.

Updated about 2 months ago