Migrate to v2.4

Details on how to upgrade to v2.4 and what to expect

The current version of the API is v2.3 and available at https://api.bridgeft.com/v2

The new version, v2.4, is largely backward compatible and hence not a major version change. However there are some small breaking changes to be aware of, as well as an opportunity to engage in the new API early.

Watch this 5 minute video for a guided overview of these changes:

And the slides to follow along:

What’s changing?

The v2.4 release largely changes the tech stack and infrastructure to enable increased performance and a larger data push. Performance gains are endpoint-specific but we’ve observed 2-15x latency reductions across the board.

We can also now push more data over the API, resulting in a larger pagination default, which is changing from 100 to 10,000. The maximum number of records that can be paginated in a single http request is increasing from 1,000 to 100,000.

Most endpoints are backward compatible with the exception of deleting data in bulk. Previously, we handled these requests using a POST. In v2.4 deletes for single and multiple objects are handled with the DELETE method.

Error responses have been reworked to include validation errors as they’re obtained, as well as an event_id which can be used to track internally reported errors for our development team to fix. This is helpful when communicating unexpected API errors to our client success team.

Finally we’ve reworked our filtering system to be more flexible, enabling much more complex queries. Unfortunately these changes are not backward compatible. If you have a use case around filtering data please review the v2.4 documentation.

Specific details on all the changes are documented in the Changelog.

Backward incompatible changes

The following changes are backward incompatible; they'll require updates to your client or integration code:

  • Filtering
  • Error messages
  • Object deletion now uses the DELETE method for both single and bulk deletes.
  • The username field has been deprecated
  • The valuetype field on billing minimums has changed to value_type for consistency

Details on these and other changes can be found on the Changelog.

Timeline

Version 2.4 will be rolled out with a migration period, allowing you time to update your integration code.

  • May 1: a new temporary domain is made available to access v2.4
    • alb.api.bridgeft.com: v2.4 of the Atlas API
    • api.bridgeft.com: v2.3 of the Atlas API
  • May: Migration period
    • We won't be making any changes to either v2.3 or v2.4 during this time, allowing you to update your integration code
  • June 1: v2.4 is deployed to api.bridgeft.com, and alb.api.bridgeft.com remains operational
    • At this time, v2.3 is no longer accessible.
    • Your integration will continue to work if it's still pointing to alb.api.bridgeft.com
  • June 30: alb.api.bridgeft.com is no longer responsive
    • You must reconfigure your integration to point to api.bridgeft.com before this date, or your integration will stop working.

We expect this will be enough time to update integration code. However, please reach out if you need more time or assistance. Above all, we don't want to break any existing integrations.

Impact and Action

You have two options: no action, or upgrade.

No action

Without taking action you’ll continue to consume the api using https://api.bridgeft.com/v2
However you should recognize the v2.4 will replace the v2.3 API. We’re tentatively planning this switch for May 31, 2021.

Depending on your case cases around filtering, error handling and object deletion your integration may break.

We don't recommend taking this route because at a minimum the endpoints consumed by your integration will no longer be documented. We'll likely deprecate these v2.3 endpoints in the future (with advance warning, of course).

Upgrading

We recommend updating your integration early, but recognize the base url will need to change twice.
To upgrade:

  1. Configure your integration to consume https://alb.api.bridgeft.com/v2
  2. Update your code. At a minimum this should mean accounting for backward incompatible changes and updating endpoints to match the v2.4 documented endpoints.
  3. Starting June 1, reconfigure your integration to consume https://api.bridgeft.com/v2