Skip to main content

Migration guide for deprecated APIs

As Imply Polaris evolves, we introduce new capabilities and make changes to our APIs that may cause compatibility issues with the existing API consumers.

This topic contains information about Imply Polaris API deprecations and how to migrate to newer API resources.

Migrate to project-scoped URL​

The introduction of multi project support in Polaris required modification of the API structure to allow for project-scoped use. Note that the actual semantics of the API and the APIs that access global resources didn't change with this update.

Support for project-less URLs has been deprecated and will be removed by the end of September 2024. For backward compatibility, you can continue to use project-less URLs to make calls against projects created before September 29, 2023.

For projects created after September 29, 2023, you must include the following path parameters in the project-scoped URL when calling regional API resources:

  • ORGANIZATION_NAME: The custom domain through which you access Polaris.
  • REGION: The cloud region of your Polaris project.
  • CLOUD_PROVIDER: The cloud service provider for your Polaris infrastructure.
  • PROJECT_ID: The unique identifier for your Polaris project.

For example: https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID

To obtain the project ID, send a GET request to the Projects API. You can also view the project ID in the UI by expanding the project selector and clicking the ellipsis next to the project name.

Update your requests to the following APIs to include the PROJECT_ID in the URL. Note that all APIs now use a v1 version identifier. See Migrate to v1 API version for more information.

  • /v0/pivot/api/v1/embed is deprecated. Use /v0/projects/PROJECT_ID/pivot/api/v1/embed instead.
  • /v1/events/CONNECTION_NAME is deprecated. Use /v1/projects/PROJECT_ID/events/CONNECTION_NAME instead.
  • /v1/files is deprecated. Use /v1/projects/PROJECT_ID/files instead.
  • /v2/connections is deprecated. Use /v1/projects/PROJECT_ID/connections instead.
  • /v2/jobs is deprecated. Use /v1/project/PROJECT_ID/jobs instead.
  • /v2/tables is deprecated. Use /v1/projects/PROJECT_ID/tables instead.

For example, update your request to the Files API as follows:

  • Old URL: https://example-org.us-east-1.aws.api.imply.io/v1/files
  • New URL: https://example-org.us-east-1.aws.api.imply.io/v1/projects/12375ffx-f7x4-4f0x-a1a6-3b3424987ee0/files

Migrate to v1 API version​

Because project-scoped APIs affected the API structure, now all Polaris APIs use a v1 version identifier.

Update your requests to the following APIs to use the v1 version identifier and include the PROJECT_ID in the URL:

  • /v2/connections is deprecated. Use /v1/projects/PROJECT_ID/connections instead.
  • /v2/jobs is deprecated. Use /v1/project/PROJECT_ID/jobs instead.
  • /v2/tables is deprecated. Use /v1/projects/PROJECT_ID/tables instead.

For example, update your request to the Jobs API as follows:

  • Old URL: https://example-org.us-east-1.aws.api.imply.io/v2/jobs
  • New URL: https://example-org.us-east-1.aws.api.imply.io/v1/projects/12375ffx-f7x4-x56x-a1a6-3b3424987ee0/jobs

Support for v2 API endpoints will be removed by the end of September 2024. For backward compatibility, you can continue to use the deprecated v2 version APIs to make calls against projects created prior to September 29, 2023. We strongly recommend updating your application to the v1 API version prior to September 2024.

Migrate to Projects API​

The Project v1 API has been deprecated in favor of the Projects v1 API. We recommend that you discontinue using the Project v1 API and move your application to the Projects v1 API.

The Project v1 API will be removed by the end of September 2024.

To migrate to the Projects API, update your requests as follows:

  • Old URL: https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/project
  • New URL: https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID

JDBC and BI tools​

Applications that integrate with Polaris using JDBC, including BI tools such as Tableau and Looker, must include the project ID in the connection URL. Support for previously established JDBC connections will be removed by the end of September 2024.

Update your JDBC connection string as follows:

  • Old JDBC connection string:

    jdbc:avatica:remote:url=https://ORGANIZATION_NAME.jdbc.REGION.CLOUD_PROVIDER.api.imply.io;transparent_reconnection=true

  • New JDBC connection string:

    jdbc:avatica:remote:url=https://PROJECT_ID--ORGANIZATION_NAME.jdbc.REGION.CLOUD_PROVIDER.api.imply.io;transparent_reconnection=true

Migrate to organization-specific URL​

The base URL for global Polaris API resources requires the organization name as a subdomain. The organization name represents the custom domain through which you access Polaris. For example, in https://exampl-org.app.imply.io, the organization name is example-org.

Update all API calls to global resources to include the organization name subdomain. For example, update your request to the Identity management API as follows:

  • Old URL: https://api.imply.io/v1/users
  • New URL: https://ORGANIZATION_NAME.api.imply.io/v1/users

Requests to id.imply.io to obtain access tokens are unaffected by this change.