openapi

Developer-friendly & type-safe Typescript SDK specifically catered to leverage openapi API.

[!IMPORTANT] This SDK is not yet ready for production use. To complete setup please follow the steps outlined in your workspace. Delete this section before publishing to a package manager.

Summary

Redis Data Integration API: API for Redis Data Integration services. Note: RDI API v1 is deprecated as of RDI 1.19.0. Use RDI API v2 for new integrations and migrate existing clients. API v1 will not be extended with new RDI features and may be removed in a future RDI version.

Table of Contents

• openapi
  • SDK Installation
  • Requirements
  • SDK Example Usage
  • Authentication
  • Available Resources and Operations
  • Standalone functions
  • Retries
  • Error Handling
  • Custom HTTP Client
  • Debugging
• Development
  • Maturity
  • Contributions

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add @rdi-ui/sdk

PNPM

pnpm add @rdi-ui/sdk

Bun

bun add @rdi-ui/sdk

Yarn

yarn add @rdi-ui/sdk

[!NOTE] This package is published with CommonJS and ES Modules (ESM) support.

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

SDK Example Usage

Example

import { RdiSDK } from "@rdi-ui/sdk";

const rdiSDK = new RdiSDK({
  serverURL: "https://api.example.com",
});

async function run() {
  const result = await rdiSDK.v1.auth.login({
    username: "admin",
    password: "secret-password",
  });

  console.log(result);
}

run();

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name | Type | Scheme | | ----------- | ---- | ----------- | | jwtBearer | http | HTTP Bearer |

To authenticate with the API the jwtBearer parameter must be set when initializing the SDK client instance. For example:

import { RdiSDK } from "@rdi-ui/sdk";

const rdiSDK = new RdiSDK({
  serverURL: "https://api.example.com",
  jwtBearer: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await rdiSDK.v1.auth.login({
    username: "admin",
    password: "secret-password",
  });

  console.log(result);
}

run();

Available Resources and Operations

V1.Actions

• getAction - Get Action

V1.Auth

• login - Login

V1.Config

• getTemplate - Pipelines Config Templates
• getConfigSchemas - Pipelines Config Schemas

V1.Jobs

• getTemplates - Pipelines Jobs Templates
• dryRunJob - Job Dry Run

V1.Monitoring

• getStatistics - Statistics

V1.Pipelines

• startPipeline - Start Pipeline
• stopPipeline - Stop Pipeline
• resetPipeline - Reset Pipeline
• getPipelines - Get Pipelines
• createOrUpdatePipeline - Post Pipelines
• patchPipeline - Patch Pipelines
• undeployPipeline - Undeploy Pipelines

V1.SecretProviders

• upsertSecretProvider - Upsert Secret Provider By Name
• patchSecretProvider - Partial Update Secret Provider By Name
• deleteSecretProvider - Delete Secret Provider By Name

V1.Secrets

• setMultiKeySecret - Set Multi Key Secret
• setSecrets - Set Secrets

V1.Sources

• deleteSource - Delete Source By Name
• dryRunSource - Sources Dry Run
• getColumns - Get Columns
• getSourceSchemas - Get Schemas
• getDatabases - Get Databases
• getMetadata - Get Metadata
• getTables - Get Tables

V1.Status

• getStatus - Get Status

V1.Targets

• deleteTarget - Delete Target By Name
• dryRunMultiple - Multiple Targets Dry Run
• dryRunSingle - Single Target Dry Run

V2.Dlq

• getAllDlqs - Get all DLQ streams with counts
• getRecords - Get DLQ records for a specific stream
• getByTableName - Get DLQ info for a specific stream

V2.Info

• getInfo - Info

V2.Metrics

• getCollections - Get Metric Collections
• getCollection - Get Metric Collection

V2.Pipelines

• getPipelines - Get Pipelines
• createPipeline - Create Pipeline
• getPipeline - Get Pipeline
• updatePipeline - Update Pipeline
• patchPipeline - Patch Pipeline
• deletePipeline - Delete Pipeline
• getPipelineStatus - Get Pipeline Status
• start - Start Pipeline
• stop - Stop Pipeline
• reset - Reset Pipeline

V2.Secrets

• getSecrets - Get Pipeline Secrets
• createSecret - Create Secret
• getSecret - Get Secret
• updateSecret - Update Secret
• deleteSecret - Delete Secret

V2.Sources

• getSchemas - Get Pipeline Source Schemas

V2.Targets

• flushTarget - Flush Target

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

• v1ActionsGetAction - Get Action
• v1AuthLogin - Login
• v1ConfigGetConfigSchemas - Pipelines Config Schemas
• v1ConfigGetTemplate - Pipelines Config Templates
• v1JobsDryRunJob - Job Dry Run
• v1JobsGetTemplates - Pipelines Jobs Templates
• v1MonitoringGetStatistics - Statistics
• v1PipelinesCreateOrUpdatePipeline - Post Pipelines
• v1PipelinesGetPipelines - Get Pipelines
• v1PipelinesPatchPipeline - Patch Pipelines
• v1PipelinesResetPipeline - Reset Pipeline
• v1PipelinesStartPipeline - Start Pipeline
• v1PipelinesStopPipeline - Stop Pipeline
• v1PipelinesUndeployPipeline - Undeploy Pipelines
• v1SecretProvidersDeleteSecretProvider - Delete Secret Provider By Name
• v1SecretProvidersPatchSecretProvider - Partial Update Secret Provider By Name
• v1SecretProvidersUpsertSecretProvider - Upsert Secret Provider By Name
• v1SecretsSetMultiKeySecret - Set Multi Key Secret
• v1SecretsSetSecrets - Set Secrets
• v1SourcesDeleteSource - Delete Source By Name
• v1SourcesDryRunSource - Sources Dry Run
• v1SourcesGetColumns - Get Columns
• v1SourcesGetDatabases - Get Databases
• v1SourcesGetMetadata - Get Metadata
• v1SourcesGetSourceSchemas - Get Schemas
• v1SourcesGetTables - Get Tables
• v1StatusGetStatus - Get Status
• v1TargetsDeleteTarget - Delete Target By Name
• v1TargetsDryRunMultiple - Multiple Targets Dry Run
• v1TargetsDryRunSingle - Single Target Dry Run
• v2DlqGetAllDlqs - Get all DLQ streams with counts
• v2DlqGetByTableName - Get DLQ info for a specific stream
• v2DlqGetRecords - Get DLQ records for a specific stream
• v2InfoGetInfo - Info
• v2MetricsGetCollection - Get Metric Collection
• v2MetricsGetCollections - Get Metric Collections
• v2PipelinesCreatePipeline - Create Pipeline
• v2PipelinesDeletePipeline - Delete Pipeline
• v2PipelinesGetPipeline - Get Pipeline
• v2PipelinesGetPipelines - Get Pipelines
• v2PipelinesGetPipelineStatus - Get Pipeline Status
• v2PipelinesPatchPipeline - Patch Pipeline
• v2PipelinesReset - Reset Pipeline
• v2PipelinesStart - Start Pipeline
• v2PipelinesStop - Stop Pipeline
• v2PipelinesUpdatePipeline - Update Pipeline
• v2SecretsCreateSecret - Create Secret
• v2SecretsDeleteSecret - Delete Secret
• v2SecretsGetSecret - Get Secret
• v2SecretsGetSecrets - Get Pipeline Secrets
• v2SecretsUpdateSecret - Update Secret
• v2SourcesGetSchemas - Get Pipeline Source Schemas
• v2TargetsFlushTarget - Flush Target

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

import { RdiSDK } from "@rdi-ui/sdk";

const rdiSDK = new RdiSDK({
  serverURL: "https://api.example.com",
});

async function run() {
  const result = await rdiSDK.v1.auth.login({
    username: "admin",
    password: "secret-password",
  }, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  console.log(result);
}

run();

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

import { RdiSDK } from "@rdi-ui/sdk";

const rdiSDK = new RdiSDK({
  serverURL: "https://api.example.com",
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

async function run() {
  const result = await rdiSDK.v1.auth.login({
    username: "admin",
    password: "secret-password",
  });

  console.log(result);
}

run();

Error Handling

SDKError is the base class for all HTTP error responses. It has the following properties:

| Property | Type | Description | | ------------------- | ---------- | --------------------------------------------------------------------------------------- | | error.message | string | Error message | | error.statusCode | number | HTTP response status code eg 404 | | error.headers | Headers | HTTP response headers | | error.body | string | HTTP body. Can be empty string if no body is returned. | | error.rawResponse | Response | Raw HTTP response | | error.data$ | | Optional. Some errors may contain structured data. See Error Classes. |

Example

import { RdiSDK } from "@rdi-ui/sdk";
import * as errors from "@rdi-ui/sdk/models/errors";

const rdiSDK = new RdiSDK({
  serverURL: "https://api.example.com",
});

async function run() {
  try {
    const result = await rdiSDK.v1.auth.login({
      username: "admin",
      password: "secret-password",
    });

    console.log(result);
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.SDKError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof errors.RedisDiApiV1ModelsResponsesErrorResponse) {
        console.log(error.data$.detail); // string
      }
    }
  }
}

run();

Error Classes

Primary error:

• SDKError: The base class for HTTP error responses.

Network errors:

• ConnectionError: HTTP client was unable to make a request to a server.
• RequestTimeoutError: HTTP request timed out due to an AbortSignal signal.
• RequestAbortedError: HTTP request was aborted by the client.
• InvalidRequestError: Any input used to create a request is invalid.
• UnexpectedClientError: Unrecognised or unexpected error.

Inherit from SDKError:

• RedisDiApiV1ModelsResponsesErrorResponse: Model representing an API error response. Applicable to 30 of 53 methods.*
• RedisDiApiModelsErrorsErrorResponse: Generic error response model. Applicable to 23 of 53 methods.*
• ExtendedErrorResponse: Model representing an API error response with an additional list of errors. Status code 422. Applicable to 9 of 53 methods.*
• ActionResponseError: Successful Response. Status code 404. Applicable to 1 of 53 methods.*
• ResponseValidationError: Type mismatch between the data returned from the server and the structure expected by the SDK. See error.rawValue for the raw value and error.pretty() for a nicely formatted multi-line string.

* Check the method documentation to see if the error is applicable.

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to:

• route requests through a proxy server using undici's ProxyAgent
• use the "beforeRequest" hook to add a custom header and a timeout to requests
• use the "requestError" hook to log errors

import { RdiSDK } from "@rdi-ui/sdk";
import { ProxyAgent } from "undici";
import { HTTPClient } from "@rdi-ui/sdk/lib/http";

const dispatcher = new ProxyAgent("http://proxy.example.com:8080");

const httpClient = new HTTPClient({
  // 'fetcher' takes a function that has the same signature as native 'fetch'.
  fetcher: (input, init) =>
    // 'dispatcher' is specific to undici and not part of the standard Fetch API.
    fetch(input, { ...init, dispatcher } as RequestInit),
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new RdiSDK({ httpClient: httpClient });

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

[!WARNING] Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

import { RdiSDK } from "@rdi-ui/sdk";

const sdk = new RdiSDK({ debugLogger: console });

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy