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

Name	Type	Description
commerce-api-key*	string	Commerce API Key.
issuer-address*	string	Contract Address of API Key owner.

Request Body

Name	Type	Description
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.

201: Created

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

Body Attribute	Description	Format
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

category	Usage	example
artwork	On issue endpoint, use it for payload.attachmentFiles[*].url	https://static-files-stg.startrail.startbahn.jp/srr-images/0xf1B51E02804A7AF4Eb4c2f57dc9a05510A513C17/221208_royalty-01-001.jpg
certificate, installation, for_authenticity	On issue endpoint, use it for payload.attachmentFiles[*].url	https://storage.googleapis.com/artwork-staging-images/srr-images/luw-address-1/certificate.tif
non_attachment_file	use it for the field in metadata on the image, payload[*].metadata.thumbnailURL or payload[*].metadata.contractTerms.fileURL	https://storage.googleapis.com/artwork-staging-images/srr-images/0xf1B51E02804A7AF4Eb4c2f57dc9a05510A513C17/Contract_Terms_test.pdf

Example

{
  "results": [
    // Example result for non_attachment_file and artwork category
    {
      "filename": "artwork.jpg",
      "contentType": "image/jpeg",
      "url": "https://storage.googleapis.com/bucket/directory/luw-address/artwork.jpg?signature=xyz",
      "finalUrl": "https://static-files.startrail.io/directory/luw-address/artwork.jpg"
    },
    // Example for other categories
    {
      "filename": "certificate.jpg",
      "contentType": "image/jpeg",
      "url": "https://storage.googleapis.com/bucket/directory/luw-address/certificate.jpg?signature=xyz",
      "finalUrl": "https://storage.googleapis.com/bucket/directory/luw-address/certificate.jpg"
    }
  ]
}

400: Bad Request

The API responds with 400 if the request body is invalid.

// If the payload is incorrect
{
  "statusCode": 400,
  "message": [
    "payload.0.category must be one of the following values: certificate,for_authenticity,artwork,installation,non_attachment_file"
  ]
}

500: Internal Server Error

The API responds with 5xx if there is an issue between the network and also storage provider, currently it is Google Cloud Storage.

// If the network is error or unknown error. Startbahn side needs to check.
{
  "statusCode": 502,
  "message": "Bad Gateway"
}

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