Create a tag: Migration guide

This guide details how the Create a tag endpoint has changed (previously known as POST /api/v1/skills 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.

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
API v2: /api/v2/tags

Input changes

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

API v1 input example

curl -X POST \
  https://app.360learning.com/skills \
  -H 'Content-Type: application/json' \
  -d '[
	{
    "name": "Active listening",
    "isMain": true,
    "externalId": "1234",
    "sourceLang": "en",
    "defaultLang": "fr",
    "translationsLangs": [
      {
        "lang": "fr",
        "published": true,
        "translators": [
          "[email protected]",
          "[email protected]"
        ]
      }
    ],
    "translations": [
      {
        "lang": "fr",
        "name": "Ecoute active"
      }
    ],
    "pathId": [
      "5f0c106968d47378d573e642"
    ],
    "courseId": [
      "5f0c106968d47378d573783"
    ],
    "programTemplateId": [
      "6398b1c5f9b8d1e21b50e09c"
    ]
  }
]'

API v2 input example

curl --request POST \
     --url https://app.360learning.com/api/v2/tags \
     --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	`sourceLang`: The source language for the skill. Removed from endpoint v2, not replaced.
Removed Body parameter	`defaultLang`: The default language for the skill. Removed from endpoint v2, not replaced.
Removed Body parameter	`translationsLangs`: Array of objects for each translation language. Removed from endpoint v2 , not replaced.
Removed Body parameter	`translations`: Translations data for the skill. Removed from endpoint v2, not replaced.
Removed Body parameter	`courseId` (Optional): Course ID to link this skill to. Removed from endpoint v2, not replaced.
Removed Body parameter	`programId` (Optional): Program ID to link this skill to. Removed from endpoint v2, not replaced.
Removed Body parameter	`pathId` (Optional): Path ID to link this skill to. Removed from endpoint v2, not replaced.

Output changes

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

API v1 output example

{
 "status": "skill_created",
 "_id": "5be2b954b44a1b6e3526e091"
}

API v2 output example

{
  "isMain": true,
  "_id": "5be2b954b44a1b6e3526e091",
  "name": "Active listening",
  "externalId": "1743"
}

Main output differences

Change type	API v1	API v2
Removed Output property	`status`: Removed from endpoint v2, not replaced.
Modified Success output	`200`	`201`: Returns the created tag.
Added Output property		`isMain` (Required): True if the tag is to be set as a main tag; false otherwise.
Added Output property		`name` (Required): The name of the tag.
Added Output property		`externalId` (Optional): The external identifier of the tag if it is being synced from external sources.