Replace a tag: Migration guide

This guide details how the Replace a tag endpoint has changed (previously known as updateSkill in v1).

💡

Key changes

• Terminology: The API v2 uses different terms for what was previously known as 'skills' in API v1.
  • Where you previously used 'skill' in API v1, you'll now use 'tag'.
  • Skill in API v2 now refers to a separate platform solution.
• Operation: The v2 endpoint performs a full replacement of a tag, meaning all required fields must be provided in the request body. In contrast, v1 allowed partial updates where any body parameter was optional (as long as at least one was provided).

Documentation links

Here is the link to the API reference for the API v2

🛑

The documentation for the API v1 is not publicly available.

Endpoint mapping

Here's the direct correlation between the v1 and v2 endpoint URLs:

• API v1: /api/v1/skills/:skillId
• API v2: /api/v2/tags/{tagId}

Input changes

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

API v1 input example

Shell

curl --request PUT \
     --url https://app.360learning.com/api/v1/skills/60b8d295f1a6623aefc9ce58 \
     --header 'content-type: application/json' \
     --data '{
       "externalId": "1743",
       "isMain": true,
       "name": "Active listening",
       "courseIds": ["60b8d295f1a6623aefc9ce59"],
       "pathIds": ["60b8d295f1a6623aefc9ce60"],
       "programTemplateIds": ["60b8d295f1a6623aefc9ce61"],
       "translations": [
         { "lang": "fr", "name": "Ecoute active" }
       ]
     }'

API v2 input example

Shell

curl --request PUT \
     --url https://app.360learning.com/api/v2/tags/507f1f77bcf86cd799439011 \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "isMain": true,
  "name": "Active listening",
  "externalId": "1743"
}
'

Main input differences

Change type	API v1	API v2
Removed Body parameter	courseIds (Optional): Courses to link this skill to. Removed from endpoint v2, not replaced.	-
Removed Body parameter	pathIds (Optional): Paths to link this skill to. Removed from endpoint v2, not replaced.	-
Removed Body parameter	programTemplateIds(Optional): Programs to link this skill to. Removed from endpoint v2, not replaced.	-
Removed Body parameter	translations(Optional): Translations for the skill, only allowed if the Globalization solution is active for the company. Removed from endpoint v2, not replaced.	-
Modified Path parameter	skillId (Required): The ID of the skill to update.	tagId (Required): The unique ID of the tag.
Modified Body parameter	isMain (Optional): Whether the skill is a main skill.	isMain (Required): Now required.
Modified Body parameter	name(Optional): The new name for the skill	name (Required): The name for the tag. Now required.

Output changes

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

API v1 output example

JSON

{ "status": "skill_updated" }

API v2 output example

JSON

{
  "isMain": true,
  "_id": "507f1f77bcf86cd799439011",
  "name": "Active listening",
  "externalId": "1743"
}

Main output differences

Change type	API v1	API v2
Removed Output property	status: Removed from endpoint v2 version, not replaced.	-
Modified Success output	200	200: The response body now returns the updated tag object directly.
Added Output property	-	isMain: New parameter returning the boolean status of whether the tag is a main tag.
Added Output property	-	_id: New parameter returning the unique ID of the updated tag.
Added Output property	-	name: New parameter returning the name of the tag.
Added Output property	-	externalId: New parameter returning the external identifier of the tag.