REST API migration guide: 20220603 to 20240415

Overview

This topic explains changes in the 20240415 version of the LaunchDarkly REST API and how to migrate to that version.

The 20240415 REST API version includes breaking changes. We strongly recommend upgrading to the latest API version as soon as possible. Specifically, the 20240415 version :

• changes several endpoints from unpaginated to paginated result sets, following common industry best practices
• removes a few infrequently used or less performant filters from some endpoints
• removes the previously deprecated Users, Users (beta), and User settings APIs

These changes are focused on improving performance and stability of the API. There are two ways to upgrade to the latest API version:

• Create a new access token and set it to use the latest version, 20240415. Replace all uses of your existing access token with this new token.

• Update the LD-API-Version header in all of your requests to 20240415. Here's how:

  To use the new version, update your request header

  LD-API-Version: 20240415
  COPY

The following sections describe how to migrate your API access tokens, the details of the API changes, and how to work with the new version. You can find a summary of these changes under Versioning in the LaunchDarkly REST API documentation. This section also includes the End of Life (EOL) information for each REST API version. The 20220603 version will reach EOL on April 15, 2025.

If you have questions or would like assistance during this transition, start a Support ticket.

Migrating your API access tokens

When you create a new API access token, by default its version is now 20240415.

Only currently supported versions are available when you create new access tokens. However, you may have older API access tokens that are set to unsupported versions.

To upgrade your integration to use a new API version, you can either create a new access token, or explicitly set the LD-API-Version header in each request. We recommend that you set the API version header explicitly.

Updating your request header

To use the new version, update your request header to include LD-API-Version: 20240415. For example:

curl -X GET 'https://app.launchdarkly.com/api/v2/projects/MY-PROJECT-KEY' \
  -H 'LD-API-Version: 20240415' \
  -H 'Authorization: EXAMPLE-API-ACCESS-TOKEN' \
  -H 'Content-Type: application/json'
COPY

Migrating your client libraries

If you are using the LaunchDarkly REST API through one of our generated client libraries, upgrade to version 16.x to use the 20240415 version.

Working with paginated endpoints

The following endpoints previously served unpaginated results, and now serve paginated results in version 20240415:

• List access tokens
• List custom roles
• List feature flags
• List segments

In each case, you can use the limit and offset query parameters to page through the results.

To page through the results, repeat each request, increasing the offset by the limit each time, until one of the following is true:

• you have found the particular result you are looking for
• the items array in the response is empty
• the offset is greater than the totalCount in the response, if available

Each paginated endpoint includes a default page size, typically 20. You can customize this as needed using the limit query parameter.

Example: Working with paginated endpoints

For example, previously your request may have looked like:

curl -X GET 'https://app.launchdarkly.com/api/v2/flags/{projectKey}' \
  -H 'LD-API-Version: 20240415' \
  -H 'Authorization: EXAMPLE-API-ACCESS-TOKEN'
COPY

Now, it should look like:

curl -X GET 'https://app.launchdarkly.com/api/v2/flags/{projectKey}?limit=20&offset=0' \
  -H 'LD-API-Version: 20240415' \
  -H 'Authorization: EXAMPLE-API-ACCESS-TOKEN'
COPY

You should repeat this request, increasing the offset by the limit each time, until you find the result you are looking for, or have paged through all of the results.

Changes to the access tokens API

In the 20240415 API version, the List access tokens endpoint is now paginated. It has a default page size of 25. The maximum for the limit query parameter is 1000.

Changes to the account members API

In the 20240415 API version, the List account members endpoint no longer supports the accessCheck filter. Additionally, the maximum for the limit query parameter is now 1000.

Changes to the custom roles API

In the 20240415 API version, the List custom roles endpoint is now paginated. It has a default page size of 20. The maximum for the limit query parameter is 1000.

Changes to the feature flags API

In the 20240415 API version, the List feature flags endpoint is now paginated. It has a default page size of 20. The maximum for the limit query parameter is 100.

Additionally, the following filters are no longer available:

• followerId
• hasDataExport
• status
• contextKindTargeted
• segmentTargeted

The compare query parameter has also been removed.

Finally, the environments field is now only included in the response if the request is filtered by environment, using the filterEnv query parameter. The filterEnv query parameter supports a maximum of three environments.

Changes to the segments API

In the 20240415 API version, the List segments endpoint is now paginated. It has a default page size of 20. The maximum for the limit query parameter is 100.

Changes to the teams API

In the 20240415 API version, the List teams endpoint no longer supports expanding the projects or roles fields in the response.

Additionally, the maximum for the limit query parameter is now 100.

Changes to the workflows API

In the 20240415 API version, the Get workflows endpoint is now paginated. It has a default page size of 20. The maximum for the limit query parameter is 200.

Additionally, the _conflicts field in the response is no longer available.

Removal of deprecated users APIs

The Users API, Users (beta) API, and User settings API were deprecated in May 2023. Following the release of the 20240415 API version, these deprecated APIs are being removed completely.