API Description - Rapidcompact Cloud

This document describes the usage of the Rapidcompact.cloud API endpoints which enable the upload of raw models, the optimization of a raw model and the download of the optimized rapid model.

Authentication

1. Get authentication token

Go to rapidcompact.cloud and click on your Initials and then on "API Tokens". There you can create and revoke tokens for the API usage. Give the token a name and click on "Create API Token". You should see the token. Note it down somewhere safe, as it is only shown once in plaintext after the creation.

Uploading a Model

2. Get presigned upload URLs for S3

To legitimize uploads to S3, presigned URLs are needed which can be retrived with the following endpoint.

⚠ Authenticate request with the <api-token>

POST https://api.rapidcompact.com/api/rawmodel/api-upload/start

Authorization: Bearer <api-token>
Content-Type: application/json

Provide the filenames of the files you intend to upload.

⚠ The filenames have to be as seen below at the moment.

// request body
{
  "filenames": ["mymodel.glb", "material.mat"]
}

The server will generate a ID for the raw model and create presigned URLs which can be used to upload files directly to S3. The URLs are unique for every file. It will also contain the link you have to call when you finished uploading all files.

A presigned URL will look like this: https://rapidcompact-models.s3.eu-central-1.amazonaws.com/rapid/f8efa270-062b-11ea-be2c-99e33dbda5fb/00.png?x-amz-acl=private&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY7SJJP4X2NUVUTN5%2F20191113%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20191113T154051Z&X-Amz-SignedHeaders=host%3Bx-amz-acl&X-Amz-Expires=3600&X-Amz-Signature=1e0135080b1fb7bb16cdb34176f7b3b17c61620e5ca40081fcb181ca829a2343

// response body
{
  "id": <id>,
  "links": {
    "s3_upload_urls": {
      "mymodel.glb": <presigned-url>,
      "material.mat": <presigned-url>
    },
    "complete_upload": "https://api.rapidcompact.com/api/rawmodels/<id>/api-upload/complete"
  }
}

3. Upload files

Upload to S3 by putting the files as binaries to their respective presigned URLs.

PUT <presigned-url>

<binary payload of the file>

4. Complete upload

Complete the upload, once all files were uploaded successfully. This will mark the raw model as optimizable.

⚠ Authenticate the request with the <api-token>

GET https://api.rapidcompact.com/api/rawmodel/{id}/api-upload/complete

Authorization: Bearer <api-token>

If the status code of the response is 200 OK, everything was successful.

{
  "data": {
    "id": 38,
    "name": "Test Model",
    "processing": false,
    "upload_status": "complete",
    "size": 1633800,
    "created_at": "2020-04-27T17:00:40+02:00"
  },
  "links": {
    "optimize": "https://api.rapidcompact.com/api/rawmodel/process/57"
  }
}

4.1 Uploading a .zip

After completing the upload of a zip archive, the server has to extract the containing files. The upload status of the raw model will be unzipping. You can check the upload status of the raw model with the following request:

GET https://api.rapidcompact.com/rawmodel/{rawmodel-id}

Optimize Model

5. Optimize Raw Model

Once a raw model is uploaded, you can optimize it with the following request:

POST https://api.rapidcompact.com/api/rawmodel/process/{id}

Provide the desired filesize of the optimized .glb file.

// request body
{
  "max_size_mb": 5,
  "config": "{ \"compact:pixelsPerUnitLength\": 200 }"
}

⚠ The value for the file size must be between 1 and 25.

⚠ Double quotes inside the config JSON string must be escaped with backslashes.

This request will respond with the created rapid model id which can further be used to check the optimization status and to get the download URLs.

// response body
{
    "user_id": 1,
    "id": 45, // rapidmodel-id
    "rawmodel_id": 38,
    "accepted": false,
    "configuration": {...},
    "optimization_status": "sent_to_queue",
    "name": "Test API 2",
    "updated_at": "2020-04-24 19:46:16",
    "created_at": "2020-04-24 19:46:16"
}

Download Rapid Model

6. Get Download URLs

The rapid model is available in different file formats. Get the download URLs for each format with the following endpoint:

Get the rapid model data corresponding to the rapid model id from request number 5 with the following endpoint:

GET https://api.rapidcompact.com/api/rapidmodel/{rapidmodel-id}
// response body
{
  "data": {
    "id":45,
    "optimization_status": "done",
    "downloads":{
      "usdz":"https://rapidcompact-models.s3.eu-central-1.amazonaws.com/rapid/e9a01637-7f0d-11ea-a7ea-02a62312ec9c/rapid.usdz?...",
      "glb":"https://rapidcompact-models.s3.eu-central-1.amazonaws.com/rapid/e9a01637-7f0d-11ea-a7ea-02a62312ec9c/rapid.glb?...",
      "obj":"https://rapidcompact-models.s3.eu-central-1.amazonaws.com/rapid/e9a01637-7f0d-11ea-a7ea-02a62312ec9c/rapid.obj?...",
      "ctm":"https://rapidcompact-models.s3.eu-central-1.amazonaws.com/rapid/e9a01637-7f0d-11ea-a7ea-02a62312ec9c/rapid.ctm?..."
    },
    ...,
  }
}

Download the files by following the received download URLs. The URLs are valid for 60 minutes.


Resource Endpoints

The following endpoints allow CRUD like manipulation of raw models and rapid models.

⚠ Authenticate the requests with the <api-token>

Raw Model

Get all raw models

GET https://api.rapidcompact.com/api/rawmodel

Get a raw model

GET https://api.rapidcompact.com/api/rawmodel/{rawmodel-id}

Delete a raw model

DELETE https://api.rapidcompact.com/api/rawmodel/{rawmodel-id}

Rapid Model

Get all rapid models

GET https://api.rapidcompact.com/api/rapidmodel

Get a rapid model

GET https://api.rapidcompact.com/api/rapidmodel/{rapidmodel-id}

Delete a rapid model

DELETE https://api.rapidcompact.com/api/rapidmodel/{rapidmodel-id}