Geometry Backend SDK TypeScript - Migration Guide

Migrating from Version 1.x.x to 2.x.x (03/11/2024)

Overview

Version 2 of the Geometry Backend API SDK has been fully re-engineered to provide greater control over request handling and response processing. The new SDK allows direct interaction with the underlying Axios library, configurable on a per-request basis. This redesign introduces breaking changes across the SDK, including renaming many types and reworking the core interaction patterns.

Data Transfer Objects (DTOs)

To maintain compatibility, the structure and property names of all Data Transfer Objects (DTOs) remain unchanged. However, the interface names have been updated for consistency. Refer to the Geometry API documentation for a full list of DTOs and their details by endpoint.

Resource Management

Previously, the SDK centered around a single client instance for all resources. For example:

TYPESCRIPT

import { create } from "@shapediver/sdk.geometry-api-sdk-v2";

// Client instance
const sdk = create("https://sdeuc1.eu-central-1.shapediver.com");

// Resource calls
await sdk.session.init("ticket");
await sdk.model.get("model-id");
await sdk.export.compute("session-id", {});

With Version 2, each resource API is instantiated directly and managed independently. This approach allows customization through a Configuration instance for each API. Additional RawAxiosRequestConfig options can be provided per individual request:

TYPESCRIPT

Copy code
import {
  Configuration,
  SessionApi,
  ModelApi,
  ExportApi,
} from "@shapediver/sdk.geometry-api-sdk-v2";

// General config
const config = new Configuration({
  basePath: "https://sdeuc1.eu-central-1.shapediver.com",
});

// Resource instantiation and calling
await new SessionApi(config).createSessionByTicket("ticket");
await new ModelApi(config).getModel("model-id");
await new ExportApi(config).computeExports("session-id", {});

// Custom configuration for a single call
await new ExportApi(config).computeExports(
  "session-id",
  {},
  { headers: { "Content-Type": "custom-content-type" } }
);

Return Objects

In Version 2, each resource API call returns an AxiosPromise object, which includes extensive information about both the request and the response. This allows direct access to details such as HTTP status, parsed response data, and headers, providing greater flexibility for handling responses. However, it introduces a small change in how resources are accessed:

TYPESCRIPT

// Example on how to extract information from the response object
const res = await new SessionApi(config).createSessionByTicket("ticket");
const status = res.status;       // HTTP status code
const headers = res.headers;     // Response headers
const session = res.data;        // Parsed response data
const request = res.request;     // Various information about the request made

// Inline access to parsed data
const model = (await new ModelApi(config).getModel("model-id")).data;

Utility Functions

Version 2 retains (and expands on) the utility functions from Version 1, with a restructured organization:

HTTP-related utilities are now encapsulated within the UtilsApi class, supporting both global and per-call configuration via Configuration and RawAxiosRequestConfig.
Other utility functions, such as extractFileInfo, exists, and processError, are provided as standalone methods.

Error Handling

Version 1 SDK errors included ShapeDiverError, ShapeDiverRequestErrorCore, and ShapeDiverResponseError. Type guards allowed distinguishing between these errors.

In Version 2, the SDK adopts AxiosError for better integration with Axios, providing detailed request and response data. For simpler handling of API-specific errors, the SDK introduces processError, which returns instances of:

SdError (analogous to ShapeDiverError)
SdRequestError (similar to ShapeDiverRequestErrorCore)
SdResponseError (similar to ShapeDiverResponseError)

Use instanceof checks to easily identify these error types. See the README for further information.