Request Signed URL for Upload/Download Files

to generate signed URLs both for uploads and downloads

POST <base_url>/port/api/v1/commerce/signedUrls

Please replace <base_url> as explained here.

Precaution

File Size

Our system currently only support file sizes with a maximum limit of strictly less than 2GB, or in other words:

    filesize < 2^31 

This essentially implies that any user interaction with our API involving data transfer would necessitate adherence to this requirement. Manifestly, if a file size exceeds the defined threshold of 2GB, it may possibly impede the operation of the application.

File Name

File name

  1. should not contain space.

  2. should contain the file extension, including but not limited to .jpg, .png, .pdf, etc.

  3. use a unique name for each file. Filename is unique perissuer-address otherwise it will fail.

    This is to avoid modification of files that are already used in SRR. However given the upgrade to the IPFS protocol, there is no need to be concerned for the filename in terms of its look. The filename is not going to exist in the minted SRR since it is going to be converted to IPFS and the filename will be replaced with cid that is a function of the file's content and not file's name.

*In order to make the file names unique anyway, you can prefix/suffix the name with a unique number such as Date.now() .

**Given the underlying usage of IPFS, there is no need to be worried about duplicated contents. Since if two files with different name but same content will eventually be replaced with the same ipfs url.

Headers

NameTypeDescription

commerce-api-key*

string

Commerce API Key.

issuer-address*

string

Contract Address of API Key owner.

Request Body

NameTypeDescription

action*

string (write and read)

Field to specify the action of the Signed URL. Value

write

to request upload signed URL, and

read

to request download signed URL.

payload*

array

Array of signed URL request.

payload[*].filename*

string

The filename must meet the constraints mentioned above.

If the client needs to delete an existing file, please contact Startbahn.

payload[*].category*

string

Please refer to this page to understand the difference among the categories.

Use non_attachment_file to upload thumbnails and contract terms.

The API responds with 201 when the signed URL is created. The validity of the signed URL is 15 minutes after it is created.

The clientโ€™s back-end needs to consider its upload speed. If the files that need to be uploaded are many, clientโ€™s back-end may consider splitting the signed URL request to ensure that all of the files are uploaded.

Body AttributeDescriptionFormat

results

results of the request

Array

results[*].filename

Name of the file, same as one in the request

string

results[*].contentType

Content-Type that was chosen and set for the file. You need to set the same value in Content-Type header when uploading or downloading the file with the signed URL. Otherwise, you will get an error about signature mismatch.

string

results[*].url

The signed URL that client can use to perform action such as upload or download. NOTE: This URL is only valid for 15 minutes and should not be saved. Please check the reference below.

string

results[*].finalUrl

The URL that client should save and use when calling issue endpoint. Check below for details

string

Usage of Final URL

categoryUsageexample

artwork

On issue endpoint, use it for payload.attachmentFiles[*].url

certificate, installation, for_authenticity

On issue endpoint, use it for payload.attachmentFiles[*].url

non_attachment_file

use it for the field in metadata on the image, payload[*].metadata.thumbnailURL or payload[*].metadata.contractTerms.fileURL

Swagger Endpoint (Test Environment)

Swagger to test.

Required Permissions

Check parent page.

Request Body Example

Signed URL for upload

// Example for thumbnail
{
  "payload": [
    {
      "filename": "thumbnail.jpg",
      "category": "non_attachment_file"
    }
  ],
  "action": "write"
}

// Example for contract terms
{
  "payload": [
    {
      "filename": "contract.pdf",
      "category": "non_attachment_file"
    }
  ],
  "action": "write"
}

// Example for other categories
{
  "payload": [
    {
      "filename": "certificate.pdf",
      "category": "certificate"
    }
  ],
  "action": "write"
}

Signed URL for Download

{
  "payload": [
    {
      "filename": "certificate.pdf",
      "category": "certificate"
    }
  ],
  "action": "read"
}

Code Example

Check parent page.

Reference

https://cloud.google.com/storage/docs/access-control/signed-urls

Last updated

ยฉ2023 Startbahn, Inc.