Migrate updateCustomUserLink

This guide outlines the changes introduced in the Replace custom user links v2 endpoint (previously known as updateCustomUserLink in v1).

💡
Key changes

Resource identification: API v2 uses specific path parameters (userId and customUserLinkId) to identify the resource. API v1 relied on a combination of mail and type within the request body.

Full resource replacement: Unlike v1, v2 requires you to provide all mandatory fields (customLinkId and url) in the request body, even if only one value is being changed.

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/{customUserLinkId}

Input changes

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

API v1 input example

curl --location -g --request PUT 'https://app.360learning.com/api/v1/customlinks?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "calendar link",
    "mail": "[email protected]",
    "update":
    {
        "url": "https://360learning.com",
        "type": "new calendar link"
    }
}'

API v2 input example

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

Main input differences

Change type	API v1	API v2
Removed Body parameter	`mail`: Email address of the user.
Removed Body parameter	`type`: Current internal name of the link.
Removed Body parameter	`update.type`: New internal name of the 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.
Added Path parameter		`customUserLinkId`(Required): The unique ID of the custom user link to be updated.
Added Body parameter		`customLinkId`(Required): The unique ID of the custom link.

Output changes

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

API v1 output example

{
  "status": "custom_user_link_updated"
}

API v2 output example

{
  "_id": "1a2b3c4d5e6f7a8b9c8d7e6f",
  "customLinkId": "1a2b3c4d5e6f7a8b9c8d7e6f",
  "url": "https://360learning.com"
}

Main output differences

Change type	API v1	API v2
Removed Output property	`status`: String confirming the update.
Added Output property		`_id`: The unique ID of the created custom user link.
Added Output property		`customLinkId`: The unique ID of the custom link.
Added Output property		`url`: The URL of the custom user link.