Migrate createCustomUserLink

This guide outlines the changes introduced in the Create a custom user link v2 endpoint (previously known as createCustomUserLink in v1).

💡
Key changes

User identification: The target user is now identified via a userId path parameter. API v1 previously used the mail property within the request body.

Resource referencing: In the request body, you must now provide the unique customLinkId. API v1 used a descriptive type string to reference the parent custom link.

Documentation links

Here are the links to the API reference for:

Endpoint mapping

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

API v1: /api/v1/customuserlinks
API v2: /api/v2/users/USERID/custom-links

Input changes

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

API v1 input example

curl --location -g 'https://app.360learning.com/api/v1/customuserlinks' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mail": "[email protected]",
    "url": "https://360learning.com",
    "type": "calendar link"
}'

API v2 input example

curl --request POST \
     --url https://app.360learning.com/api/v2/users/507f1f77bcf86cd799439011/custom-links \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "customLinkId": "628397d2a55c96814de83322",
  "url": "https://360learning.com"
}
'

Main input differences

Change type	API v1	API v2
Removed Body parameter	`mail` (Required): Used to identify the user.
Removed Body parameter	`type`(Required): The descriptive internal name used to identify the custom link.
Added Header parameter		`360-api-version` (Required): API version identifier. Example: `v2.0`.
Added Path parameter		`userId` (Required): The unique ID of the user, now included in the URL path.
Added Body parameter		`customLinkId` (Required): The unique system ID of the custom link. This replaces the type parameter used in v1.

Output changes

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

API v1 output example

{
  "customUserLink": {
    "_id": "628398fdfa066876f0091e23",
    "userId": "507f1f77bcf86cd799439011",
    "customLinkId": "628397d2a55c96814de83322",
    "url": "https://360learning.com"
  },
  "status": "custom_user_link_created"
}

API v2 output example

{
    "customLinkId": "628397d2a55c96814de83322",
    "url": "https://360learning.com",
    "_id": "682c9df2aa08d549dddd7b86"
}

Main output differences

Change type	API v1	API v2
Removed Output property	`status`: String confirming creation.
Removed Output property	`userId`: The ID of the user assigned to the link.
Modified Success output	`200 OK`	`201 Created`
Modified Output properties	Response nested within a `customUserLink` object.	Flattened response returning the created link object directly.