Overview

ShapeDiver Geometry Backend Systems are used to

  • host Grasshopper models in a secure and scalable way,

  • run computations of Grasshopper models, and

  • cache the results of computations and exports.

Geometry Backend API

Geometry Backend Systems provide an API that allows to

  • manage the Grasshopper models,

  • trigger computations,

  • request the results of computations and download resulting assets,

  • upload assets which serve as input data for the Grasshopper models, and

  • get related data like usage analytics and computation logs.

Note: The Viewer directly communicates with the API endpoint of the Geometry Backend System which your Grasshopper model is hosted on. This API endpoint is also known as the modelViewUrl in the context of the viewer. See below for the API endpoints of our shared systems.

Getting started – SDKs and examples

We provide an SDK for JavaScript and TypeScript via npm. Please check out how to use it and the examples provided there: https://www.npmjs.com/package/@shapediver/sdk.geometry-api-sdk-v2

An SDK for .NET/C# will be released in Q1 2022.

We provide these examples on github. Ask us on the Forum if you don’t understand how they work, or you want suggest further examples to be added.

Authorization

You need a ticket (an API key) for your model in order to access it using the Geometry Backend API. Please use the Platform to obtain a ticket depending on the type of your application:

The Geometry Backend also supports a stronger authorization mechanism by means of ticket and a short-lived JWT. Some functionality of the Geometry Backend API requires the use of a JWT.

The Platform Backend API offers functionality for obtaining both JWT and ticket for your model. You will be able to use this once we have released the Platform Backend API in Q1 2022, we are finalizing some details.

Sessions and their lifetime

Some of the Geometry Backend API's functionality is based on sessions. This applies to running computations, downloading results, and uploading input assets. You need to make an initial API call which creates a session. All further API calls then include the unique id of the session in the path of the URL.

An example:

Session init call (creates a new session):

curl -X POST https://sdr7euc1.eu-central-1.shapediver.com/api/v2/ticket/{BACKEND_TICKET}
CODE

The resulting JSON object contains a property called sessionId.

Computation request (URL includes sessionId in path):

curl -X PUT https://sdr7euc1.eu-central-1.shapediver.com/api/v2/session/{sessionId}/output \
  --header 'Content-Type: application/json' \
  --data '{"PARAMETER_ID_1":"PARAMETER_VALUE_1","PARAMETER_ID_2":"PARAMETER_VALUE_2"}'
CODE

Export request:

 curl -X PUT https://sdr7euc1.eu-central-1.shapediver.com/api/v2/session/{sessionId}/export \
  --header 'Content-Type: application/json' \
  --data '{"parameters":{"PARAMETER_ID_1":"PARAMETER_VALUE_1","PARAMETER_ID_2":"PARAMETER_VALUE_2"},"exports":{"id":"EXPORT_ID"},"max_wait_time":MSECS_TO_WAIT}'
CODE

Geometry Backend sessions have a lifetime of at most 2 hours, and in addition they are closed after a maximum inactivity timeout of 1 hour. You can also close them yourself by making a “Close session” call (good practice for your backend applications). This means that download links will become invalid after the lifetime of the session, i.e. they are not meant to be stored in your application.

In case you make a request for a session that has already been closed or timed out, you will receive an SdSessionGoneError (please refer to the Swagger documentation) and HTTP status code 410. It is good practice to handle this error in your application, create a new session, and continue using it without the user of your application noticing. The Viewer takes care of this as well.

API endpoints

In the context of the viewer the API endpoint is called modelViewUrl.

Geometry Backend System

API endpoint, modelViewUrl

Docs

Shared Rhino 7 system

https://sdr7euc1.eu-central-1.shapediver.com

Swagger

Shared Rhino 6 system

https://sdeuc1.eu-central-1.shapediver.com

Swagger

Shared Rhino 5 system

https://model-view.shapediver.com

Swagger

API documentation

Low level Swagger API documentation can be found here: https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/