From the first release of Idomoo Metadata API, the IDM upload method used was very simplistic. You simply uploaded a file, no matter the size. This of course resulted in an open pipe between you, the user, and Idomoo, which is never healthy.

Idomoo is transitioning into a different method of uploading files, which has backward compatibility implications, and actions you need to take!

The affected endpoints are:

DescriptionMethodEndpoint
Upload New ScenePOST/scenes/?library={libId}
Replace ScenePUT/scenes/{scene_id}


The New IDM Upload API

The new IDM Upload API has two stages: requesting an upload link, putting the file into that link. You can also choose to check the status of the scene's availability. Let's look at each of these stages in detail:


Stage 1: Request Upload Link

To request an upload link, use one of these endpoints:

DescriptionMethodEndpoint
Upload New ScenePOST/scenes/?library={libId}&filename={filename}
Replace ScenePUT/scenes/{scene_id}&filename={filename}


Some notes:

  • Both query parameters are mandatory.
  • There's no body in either requests.
  • The link expires after 10 minutes.


Success response:

{
    "scene_id": {sceneId},
    "ref": "{link to GET scene information}",
    "url": "{link to upload to}"
}


Success example:

{
    "scene_id": 93097,
    "ref": "https://usa-api.idomoo.com/api/v2/scenes/111",
    "url": "https://idm-upload-usa.s3.eu-west-1.amazonaws.com/6b49a2f2-933b-423a-90ef-17c14b44e6e8/3546/null/103047/Insurance_scene4new.idm?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20211007T091516Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Credential=AKIA3M633XOFCUUZNA4G%2F20211007%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=36d362ac9397d878b61dfdd9ff52129c004289d21aabecb82382a5e93a501asd"
}


Stage 2: Upload IDM to URL

To upload the file, use the upload URL using the HTTP method PUT. Responses from this endpoint are supplied by AWS S3. Idomoo has no control over them. You can only use this URL to successfully upload the file named in stage 1 once.


Checking the Status of Scene

At any point in the IDM upload process you can check the status of the scene by using the URL in the "ref" field of your stage 1 response. The possible options are:


StatusDescriptionNote
Waiting for FileA scene upload was requested but the file hasn't been uploaded yet.This is the only new status. The rest were always available.
In ProcessInitial status
ExportingUnpacking the IDM file
Rendering PreviewRendering video and thumbnail with default data
ErrorAn error occurred and the scene is not available
DoneThe scene is ready for use


Transition To The New Method

The same endpoint currently used for API IDM upload is going to switch from the old method to the new method on November 8th, 2021.

To facilitate the ease of switching to the new method Idomoo has created two new endpoints:

Existing method endpoint

https://old-usa-api.idomoo.com/api/v2https://old-eur-api.idomoo.com/api/v2

New method endpoint

https://beta-usa-api.idomoo.com/api/v2https://beta-eur-api.idomoo.com/api/v2


The suggested transition workflow is:

  1. Switch your existing implementation to the new endpoint that supports the current implementation.
  2. Do the development work to support the new 2-stage method using the temporary beta endpoint.
  3. Once you are satisfied with your development, and the switch date has passed, change the endpoint back to the original.
  4. Note that the temporary endpoints will no longer work after the cut off date mentioned below.

Here's a complete list of dates for the availability of temporary endpoints.

DescriptionDate
Date from which both temporary endpoints are availableOctober 11th, 2021
Date of switchNovember 8th, 2021
Date of temporary endpoints terminationJanuary 31st, 2022