Migrate getAllCustomUserLinks

This guide outlines the changes introduced in the List all custom user links for a user v2 endpoint (previously known as GET getAllCustomUserLinks in v1).

💡
Key changes

User identification: The API v2 identifies the user via a userId path parameter. API v1 previously used a mail query parameter.

Pagination: The v2 endpoint is paginated with a page size of 1,000 custom links. A Link header is provided to fetch subsequent pages.

Schema updates: API v2 changes the response structure to focus on unique identifiers (_id, customLinkId) and the url. To retrieve iconName, name, and type, use the List custom links endpoint.

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?mail=geralt%40rivia.pl
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

https://app.360learning.com/api/v1/customuserlinks?mail=geralt%40rivia.pl

API v2 input example

curl --request GET \
     --url https://app.360learning.com/api/v2/users/userId/custom-links \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token'

Main input differences

Change type	API v1	API v2
Removed Query parameter	`mail`: Used to identify the user via their encoded email address.	Replaced by `userId`.
Added Header parameter		`360-api-version` (Required): API version identifier. Example: `v2.0`.
Added Path parameter		`userId`: The unique ID of the user, now included in the URL path.

Output changes

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

API v1 output example

[
  {
    "url": "https://360learning.com",
    "iconName": "agenda",
    "name": "Calendar",
    "type": "calendar link"
  }
]

API v2 output example

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "customLinkId": "507f1f77bcf86cd799439011",
    "url": "https://360learning.com"
  }
]

Main output differences

API v2 introduces pagination and a simplified schema. Descriptive properties are removed from this endpoint to focus on resource identification.

Change type	API v1	API v2
Removed Output property	`iconName`: Name of the icon. Predefined values are: `default`, `agenda`, `absence`, `certificate`, `convention`, `survey` and `inbox`.	Use the List custom links endpoint for these fields.
Removed Output property	`name`: Name of the custom link.	Use the List custom links endpoint for these fields.
Removed Output property	`type`: Internal name of the link.	Use the List custom links endpoint for these fields.
Modified Success output	`200`: Returns a non-paginated list of custom link objects	`200`: Returns a paginated list (max 1,000). Includes a `Link` header to fetch the next page.
Added Output property		`customLinkId`: Unique identifier for the link resource