API geometric

Hi what is de latest version to use?
Plus were can we find >>

bearerAuth (http, Bearer)

clientAuth (apiKey)

for authorization


Please check out this section of our documentation: Developers
Let me know if you have any questions.

@user3124 are you using the SDK we provide? If so, please see section Usage - Ticket only.

Hi Alexander,

In the page you send the link there is:

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.

3 questions:

  1. de link in the document links to ShapeDiver Platform Backend API . looks like this is V1 (so the old one) The other link we have is ShapeDiver Geometry Backend API v2 this one links to v2. But we are told to use V3. So what is the correct link?

  2. when we are in the swagger environment. we need to have authorisation info:

JwtAuth (http, Bearer) value
CredentialsAuth (http, Basic) (username + password)

How do we obtain the JwtAuth (http, Bearer) value?
where do we get CredentialsAuth / which credentials should we use for CredentialsAuth ?

  1. how long is a SessionID ( for the download of a file / object session nr) valid? 30 min 3 months / 1 year? If this is e.g. 6 month it is easier for development to let the user download the files.

When the questions are not 100% clear please let me know.

kind regards

Many thanks for your detailed request, I will answer in several parts.

Disambiguation regarding APIs

Geometry Backend API

The Geometry Backend is where your Grasshopper models are hosted, computations are run, and results of computations are cached.
The latest version of the Geometry Backend API is v2. The Geometry Backend API SDK v2 corresponds to this version of the Geometry Backend API. This is the API / SDK to use in case you want to run computations or exports.

Platform Backend API

The Platform Backend is where users of the ShapeDiver Platform and their models are managed. While the documentation of the Platform Backend API is already available, we have not publicly released the API yet because we are finalizing some details, but the release will definitely happen in Q1 2022. At this time we will also make the Platform Backend SDK publicly available. The version of the Platform Backend API and SDK that will be released is v1.

Note that there is no need for you to use the Platform Backend API in order to access your models and run computations, more on that below.

Viewer API

The latest available version of our Viewer is v3. The Viewer offers an API on its own, which is not a REST API but simply a well defined API which is used to control the viewer when embedding it into web applications.
Our Viewer is a client application of the Geometry Backend, it talks to the Geometry Backend system using the Geometry Backend API explained above.

Authentication for the Geometry Backend API

As explained here it is possible to authenticate using “Ticket only” or “Ticket and JWT”. However the second case is practically not yet available to our users as long as the Platform Backend API has not been released (because only the Platform Backend API can you provide you with JWTs for your models). Therefore please refrain to use “Ticket only” authentication for now. Switching to “Ticket and JWT” will easily be possible once we have released the Platform Backend API.

Lifetime of sessions when using the Geometry Backend API

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. 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.

Please let me know whether you have any questions left.

@user3124 we have updated our help section regarding these topics: Developers

Hi @snabela,

Thank you for updating the documentation. We do not want to use the SDK as we only want to export the results of a specific session. As i understood it correctly we are creating a session (2433f374-afa1-4e1b-b70b-a0d745a7980a) for a ticket with the viewer.

With that we should be able to retrieve the exports via an api call eg : PUT: https://sdeuc1.eu-central-1.shapediver.com/api/v2/session/2433f374-afa1-4e1b-b70b-a0d745a7980a/export
the result of this call is {
“error”: “SdSessionGoneError”,
“desc”: “Session timed out”,
“message”: “Session not found”

What are we doing wrong here!

It’s ok if you do not want to use the SDK, you can also directly make requests to the Geometry Backend API.

There seems to be a misunderstanding regarding sessions, please read again this section, specifically the yellow box explaining the lifetime of sessions. Sessions have a lifetime of at most two hours, they are not permanent.

From your previous posts in this thread I am guessing that you want to run exports and download the resulting export asset from a backend application (please explain if this assumption is wrong). In your backend application you need to do these steps when using the Geometry Backend API directly (links lead to the API documentation):

  1. Initialize a new session: You can find the sessionId property in the response body).
  2. Send export request: Include a high max_wait_time (milliseconds) in your request body to make the response wait for the export to complete. The exports.id must be set to the id of the export you are requesting.
  3. Depending on the export id you requested, you will find the export result in the exports property of the response body.

Hi @snabela, thank you for your answer.

Maybe i need to explain it a little bit more. We are using the viewer to render and play with a model using a specific ticket. We understand that a session is created and lives around the 2 hours. When the user wants to buy the result of his modified design we want to give him/her a downloadlink after the payment is performed. Therefore we need to export the files within that 2 hours and keep the exports save somewhere on a S3 bucket, because the client is be able to download it afterwords

We thought to use that sessionId created by the viewer in the backend api to retrieve the exports. Is that doable?

If I understand correctly, you want to immediately perform the download once the user checks out, and save the file on your own S3 bucket.

Ideally you would trigger the export request through your backend application (as I described above, steps 1-3), because then the download link will never be exposed to your frontend.

As an alternative you could trigger the export in your frontend (using the viewer), and pass the resulting download link from your frontend to your backend.

Please let me know whether you have further questions about this.

hi @snabela,

Unfortunately we are still struggling with something what should be easy. Please read the pdf doc and hopefully you can say what we are doing wrong, but it looks to me as a bug.
shapediver session issue with viewer and geometry-api.pdf (207.3 KB)

Thank you for your quick reply!

The session id is not meant to be shared between your frontend and your backend application. While you technically can try to do that, it’s not a wise choice and we strongly recommend to not do it, because it will make your application insecure. Furthermore sessions have a limited lifetime, please see the yellow box in our documentation here:

This is the reason why you got an error telling you that the session was gone.

I am not sure what exactly you want to achieve, it would be useful to know more details in order to support you better, please explain. Lacking further knowledge I am assuming you want to download an exported file from your backend application. To achieve that, please do the three steps explained in this post from your backend application (not using the viewer).

One more thing: In your pdf document I noted that you did not include parameter values in your export request, which means you would get the exported file for the default parameter values of the model, which is probably not what you want.