Sessions and their lifetime

Some of the Geometry Backend API's functionality is based on so-called sessions. This applies to running computations, downloading results, and uploading input data. The usage of sessions is related to billing of the API usage, as well as protecting your models from unauthorized access.

You need to make an initial API call to create a session. All further API calls then include the unique id of the session in the path of the URL.

Using one of our SDKs or examples will give you a great headstart.

An example using cURL:

Session init request (creates a new session):

CODE

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

The resulting JSON object contains a property called sessionId.

Computation request (URL includes sessionId in the path):

CODE

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"}'

Export request (URL contains sessionId in the path):

CODE

 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}'

Geometry Backend sessions have a lifetime of at most 1 hour, 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 (which is 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.