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. The actual semantics of the API and the APIs that access global resources didn't change with this update.

Project-less URLs have been deprecated and will be removed by the end of September 2024. Projects created before September 29, 2023 can continue to use project-less URLs until the end of September 2024.
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. v2 API endpoints have been deprecated and will be removed by the end of September 2024. Projects created before September 29, 2023 can continue to use the deprecated v2 API endpoints until the end of September 2024.

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

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

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

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

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

  • Old URL: https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v0/projects/PROJECT_ID/pivot/api/v1/embed
  • New URL: https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/embedding-links

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.jdbc.REGION.CLOUD_PROVIDER.api.imply.io;transparent_reconnection=true