API Reference

Storage

All files are identified by means of a file key, which can be exchanged for a pre-signed, temporary, and publicly accessible URL through the storage service. For new files (uploads) a new file key and pre-signed url can be generated. Pre-signed URLs are valid for 15 minutes by default.

Uploading Files

Uploading a file to Orbit consists of three main steps:

  1. Generate a Pre-Signed Upload URL: Use the Orbit API to generate a pre-signed URL. This URL allows secure, temporary access for uploading a file to Orbit’s cloud storage. The filename used in this step represents the target name in Orbit cloud storage. It should not be a local file path or contain directory separators (i.e., “/”), though it’s not strictly forbidden.

    🚧

    Prevent Overwriting Files

    The API will not warn or prevent you from overwriting an existing file. It is highly recommended to randomly generate at least part of the filename to avoid conflicts and prevent data loss caused by overwriting.


  1. Upload the File: Once you have obtained the signed URL, perform a PUT request to upload the file. This is a standard S3 file upload to the URL obtained in the previous step. The method of uploading the file depends on your programming environment. Using the S3 utilities from the AWS SDK is the easiest method, but any HTTP library should be capable of doing this.

    📘

    API Testing Apps (e.g. Postman)

    To upload a file using an API testing app such as Postman, initiate a PUT request. Set the request URL to the pre-signed URL and select the “Body” tab. Choose the “binary” (sometimes also called "file") option, which allows you to select an input file from your local system.


  1. Link the File to a Tour (or other object): After successfully uploading the file, use the create tour action API endpoint (or any other endpoint that accepts file keys) to attach the uploaded file as proof to a specific tour. Once linked, the file will be accessible in all Orbit applications (where applicable).

Downloading Files

The process of downloading files from Orbit consists of two simple steps:

  1. Generate a Pre-Signed Download URL: To download a file, you first need to generate a pre-signed URL using the file’s key. This URL allows temporary access to the file stored in Orbit’s cloud storage. The URL is valid for a limited time (15 minutes by default), providing secure access to the file.
  2. Download the File: Once the pre-signed URL is generated, you can download the file by sending a GET request to this URL. This will retrieve the file from Orbit cloud storage.