Migrating from REST v1 to REST v2 - Platform - BlueCat Gateway - 24.1

Gateway Administration Guide

Product name
BlueCat Gateway

Only one of the Address Manager REST v2 API or the Address Manager REST v1 API clients can be active within a single Gateway instance. As such, if you want to use the REST v2 client but have custom workflows that use the REST v1 API client, you must plan a migration of your system to rebuild those workflows to use the newer client.

Note: For more details on deciding when (or whether) you should migrate to REST v2, see Choosing between the REST v1 and REST v2 APIs.

In general, you will:

  1. Set up a separate test environment for the updated workflows.

  2. Rewrite and test workflows in that test environment.

  3. When you're satisfied that the new workflows are functioning correctly, install the updated workflows in your live (or "Production") environment.

    Note: We strongly recommend you prepare a rollback procedure to restore the previous functionality to your Production environment, in case an unforseen problem occurs.

Details of your migration plan depend on the specifics of your system. Some best practices are below.

Build and test the updated workflows in a separate test environment

If you haven't already done so, set up a private, test environment with a separate instance of Gateway. Use this environment for testing changes.

If you are building the new workflows to use only REST v2, you can set this Gateway instance to use the REST v2 client. (See Setting the Address Manager REST API client version.) If you're building a hybrid workflow that works with both the REST v1 and REST v2 clients, you can switch the test Gateway instance as needed.

Consider hybrid workflows that work with both REST v1 and REST v2

In this context, a "hybrid" workflow is one that works with both the REST v1 API client and the REST v2 client. Whenever a script needs to access the API client, it first checks for the existence of the REST v2 client. If it finds it, the calls use syntax and functionality for the REST v2 client. If it does not find it, it uses the equivalent calls for the REST v1 client.

For more details, see Building workflows that work with both REST v1 and REST v2.