Migrate from RDI API v1 to v2

Migrate RDI API clients from API v1 to API v2

RDI API v1 is deprecated as of RDI 1.19.0. Existing v1 endpoints remain available for backward compatibility, but Redis recommends moving all integrations to API v2. API v1 will not be extended with new RDI features and may be removed in a future RDI version. See the RDI API reference for the current request and response schemas.

What changes in API v2

API v2 uses the pipeline resource to represent the current state of a pipeline. Operations update that resource and return its current state, so applications no longer need to poll a separate action ID. API v2 scopes related operations under a pipeline name in the request path.

The API version is part of the URL. Update /api/v1 requests to use /api/v2 where a corresponding v2 endpoint is available. You should also review the request and response models, because they can differ between versions.

Endpoint mapping

API v2 also adds endpoints for DLQ inspection, target flushing, metric collections, and API information. See the API reference for the complete list.

v1 endpoints without a v2 equivalent

Most v1 endpoints have a v2 replacement. However, the following endpoints remain available under v1 because the current API v2 design does not define a corresponding endpoint:

Replace action polling with pipeline-status polling

In API v1, a pipeline operation returns an action ID. The client then repeatedly requests that action until it finishes:

# Start a pipeline with API v1
action=$(curl -sS -X POST "$RDI_URL/api/v1/pipelines/start" \
  -H "Authorization: Bearer $RDI_TOKEN" \
  | jq -r '.action_id')

# Poll the action until it completes
curl -sS "$RDI_URL/api/v1/actions/$action" \
  -H "Authorization: Bearer $RDI_TOKEN"

With API v2, you should instead include the pipeline name in the operation URL to read its status. The operation response contains the current pipeline state. You can check the pipeline's status by polling its status endpoint, as shown below:

pipeline=default

# Start the pipeline with API v2
curl -sS -X POST "$RDI_URL/api/v2/pipelines/$pipeline/start" \
  -H "Authorization: Bearer $RDI_TOKEN"

# Poll the pipeline status while the operation is in progress
while true; do
  status=$(curl -sS "$RDI_URL/api/v2/pipelines/$pipeline/status" \
    -H "Authorization: Bearer $RDI_TOKEN")
  phase=$(printf '%s' "$status" | jq -r '.status')
  current=$(printf '%s' "$status" | jq -r '.current')
  printf '%s\n' "$status"

  case "$current:$phase" in
    true:started|true:error) break ;;
    *) sleep 2 ;;
  esac
done

Note:

• The successful state depends on the operation. For a stop, reset, update, or create operation, wait for the corresponding successful state returned by the API. For example, wait for stopped instead of started for a stop operation.
• Only accept a terminal status when current is true. When it is false, the status is outdated, so continue polling.
• Always handle error as a failed operation. Use the status values documented by the API response for the operation you are performing to check for errors.
• Do not expect an action ID from API v2.

Migration steps

1. Find the applications, scripts, and SDKs in your environment that use /api/v1.
2. Add the pipeline name to each v2 request. The only pipeline in 1.19.0 is always named default.
3. Check the pipeline response, or call GET /api/v2/pipelines/{name}/status, instead of polling an action ID.
4. Use POST /api/v2/pipelines, PUT /api/v2/pipelines/{name}, or PATCH /api/v2/pipelines/{name} to update source, target, processor, and secret-provider settings as needed. When using PATCH, omit the configuration sections that you do not want to change.
5. Use GET /api/v2/pipelines/{name}/metric-collections/{collection_name} for monitoring and GET /api/v2/pipelines/{name}/source-schemas/{source_name} for source metadata.
6. Test creating, updating, validating, starting, stopping, resetting, and deleting a pipeline on a non-production RDI 1.19.0 or later installation before updating production applications.

Authentication and the API base URL do not change. The migration requires updates to the endpoint paths, pipeline scoping, request models, and operation status handling.