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

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

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

{ "status": "skill_updated" }

API v2 output example

{
  "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.