@shapediver/sdk.geometry-api-sdk-v2

ShapeDiver Geometry Backend API - SDK v2

:warning: Version 1 is deprecated. Please upgrade to v2 to receive the newest features - Migration Guide.

ShapeDiver is a cloud platform for building online applications based on parametric 3D files made with Rhinoceros 3D and Grasshopper.

Using the ShapeDiver Geometry Backend API allows accessing ShapeDiver models without using the ShapeDiver Viewer. The SDKs provide the functionality to communicate with a specific version of our Geometry Backend API, and they expose all TypeScript-types describing request and response objects.

This SDK provides functionality to communicate with the ShapeDiver Geometry Backend API v2 and exposes all TypeScript-types describing request and response objects. See the API documentation for more details.

Authentication

The authentication system for the Geometry Backend API is based on ticket objects and JWT tokens, which are handled by the ShapeDiver Platform. You can obtain tickets and JWT tokens by

• using your account on the ShapeDiver Platform (tickets only), or
• you can obtain them programmatically using the ShapeDiver Platform API (both tickets and JWT tokens).

An SDK for the ShapeDiver Platform API will be released soon.

When obtaining a ticket for your model from the ShapeDiver Platform, please be aware that you will need a

• ticket for direct embedding in case you are accessing the Geometry Backend API from a web browser, or a
• ticket for backend access in case you are accessing the Geometry Backend API from an arbitrary client application that is not a web browser.

Base URL

The base URL to use depends on which ShapeDiver Geometry Backend System your model was uploaded to. You can find the base URL in your model's dashboard on the ShapeDiver Platform, it is also called the model view url.

Usage - Ticket only

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

(async function () {
    # Please see above on how to obtain a ticket
    const ticket = "8b23fae66cf535719a9ec797e390208b2003e3cfc894b7624ada2f6894515f8836a4-66303337623538322d34386"

    # Initialize the SDK by providing the base URL
    const sdk = create("https://sdeuc1.eu-central-1.shapediver.com")

    # This initializes a new session and returns your ShapeDiver Model and your session
    const res = await sdk.session.init(ticket)
    console.log(res)
})()

Usage - Ticket and JWT

It is possible to configure your ShapeDiver models such that JWT tokens are required to communicate with them, which provides a strong authorisation mechanism. In this case you will need to use the ShapeDiver Platform API to obtain a JWT token for your model on demand.

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

(async function () {
    # Please see above on how to obtain a ticket and a JWT
    const jwt = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikp1c3QgYSB0ZXN0IiwiaWF0IjoxNjE4OTExMjcxLCJleHAiOjE2MTg5MTQ4OTcsImp0aSI6IjYzMjA3ODE3LWJiNWQtNDY3Zi04NzRkLWM4N2EyYzAxYmZlZCJ9.S5Ps_Fx5p6aJxdBOJMBKgpf2SIlp--6kkIZU55tiqEg"
    const ticket = "8b23fae66cf535719a9ec797e390208b2003e3cfc894b7624ada2f6894515f8836a4-66303337623538322d34386"

    # Initialize the SDK by providing the base URL and your JWT
    const sdk = create("https://sdeuc1.eu-central-1.shapediver.com", jwt)

    # This initializes a new session and returns your ShapeDiver Model and your session
    const res = await sdk.session.init(ticket)
    console.log(res)
})()

Handling Errors

The SDK provides type guards to distinguish between error types.

import {
  isGBError,
  isGBGenericError,
  isGBRequestError,
  isGBResponseError,
} from "@shapediver/sdk.geometry-api-sdk-v2"

try {
  sdk.model.get("be5d4ce5-f76d-417d-8496-1f038e6f0cab")
catch (e: any) {
  if (isGBRequestError(e)) {
    // e is a request error.
    // In this case, the request was made but no response was received.
  }

  if (isGBResponseError(e)) {
    // e is a response error.
    // In this case, the request was made and the server responded with a status code that falls
    // out of the range of 2xx.
  }

  if (isGBGenericError(e)) {
    // e is a generic error.
    // Generic errors are used for everything that is neither a request error nor a response error.
  }

  if (isGBError(e)) {
    // e is either a generic error, request error or response error.
  }
}

Examples

Some practical use cases, we will regularly extend the list:

• A Twitter Bot calling a ShapeDiver Model: This example shows how to run computations using a ShapeDiver Model which has image and data inputs and outputs.

Support

If you have questions, please use the ShapeDiver Help Center.

You can find out more about ShapeDiver right here.

Licensing

This project is released under the MIT License.