Sitoo Media Object Storage

The Media Object Storage Service provides secure, scalable media management for Sitoo and its integrated applications. It enables direct client-to-cloud uploads to Amazon S3, with fast global access via CloudFront.

The service provides automated image processing upon upload, including:

• JPEG Conversion: Converting images to universally supported JPEG format.
• EXIF Stripping: Removing metadata for privacy compliance.
• Dimension Capping: Automatically resizing images to a maximum of 4096px on the longest side.
• Thumbnail Generation: Automatically creating 256x256 thumbnails for fast previews.

Authentication

All API endpoints require Bearer token authentication with account-level permissions via Sitoo's standard authentication mechanism. Your integration service must include the appropriate authorization header when interacting with the Media Object Storage endpoints.

Errors

When a request is not successful, an error object is returned. It consists of an error_code, an error_data object containing a message, and a request_id.

The error_code will be one of the following values:

• INVALID_REQUEST — The request body or parameters are invalid
• ACCESS_DENIED — Authentication failed or insufficient permissions
• FILE_NOT_FOUND — The requested file does not exist
• INTERNAL_ERROR — An unexpected server error occurred

Example error response:

{
  "error_code": "INVALID_REQUEST",
  "error_data": {
    "message": "Invalid request parameters"
  },
  "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Architecture

The Media Object Storage service is designed using a Client Orchestration pattern. This means the client application directly orchestrates media uploads and downloads with the Media Object Storage Service, rather than proxying media through other backend services (like a Shipment Service or e-commerce backend).

This architecture keeps backend services independent from media complexity, leverages direct S3 uploads for maximum performance, and ensures fast global delivery using the CloudFront CDN.

The Power of Standard S3 Uploads

By utilizing standard Amazon S3 pre-signed URLs for the actual file transfer, the Media Object Storage service provides exceptional flexibility and reliability:

• SDK Independence: Clients are not forced to bundle heavy AWS SDKs. A simple HTTP POST request using standard networking libraries (like fetch in JavaScript, or URLSession in Swift) is all that's required to upload a file.
• Resiliency & Resumability: Because it uses the industry-standard S3 API, clients can easily leverage multipart uploads, retry logic, and resume capabilities for large files or poor network conditions.
• Extensive Documentation: Developers can rely on Amazon's vast ecosystem of documentation, tools, and community knowledge for optimizing S3 uploads.

Data Flow

The media upload and download processes follow a 2-step direct-to-cloud approach.

Uploading Media

1. Request Upload URL: The Client Application requests an upload URL by calling POST /v1/media/upload-url, providing the file's metadata, including its content type and associated entity details.
   • Supported upload formats: image/jpeg, image/png, image/webp, image/gif.
   • Note: HEIC/HEIF images should be converted to JPEG on the client device prior to requesting an upload URL.
2. Direct Upload: The service responds with a pre-signed S3 upload URL and a fields object. The Client Application uploads the file directly to Amazon S3 using a form-based POST request, including all provided fields. See the AWS S3 Pre-signed POST documentation for details.

Once the upload completes, the Media Object Storage service automatically processes the original file, generating a standardized JPEG image and a thumbnail, ready for download.

Downloading Media

1. Request Download URL: The Client Application queries the Media Object Storage Service for a specific file (e.g., GET /v1/media/{file_id}) or performs a search by entity.
2. Direct Download: The Media Object Storage Service responds with file metadata that includes CloudFront signed URLs for both the processed full-size image (download_url) and its thumbnail (thumbnail_url). The Client Application then downloads the image securely and quickly from the nearest CDN edge node.

File Processing States

After a file is uploaded, it moves through the following processing states:

• uploading: Upload URL has been generated, waiting for the file to arrive.
• uploaded: File received, queued for processing.
• processing: Image conversion and thumbnail generation in progress.
• ready: Processing complete. The download_url and thumbnail_url fields are now available.
• failed: Processing encountered an error. The file is not available for download.

Entities and Linking

Photos in the Media Object Storage service are typically linked to specific domain entities (like a specific shipment or product). This is achieved through the use of an entity_type and an entity_id.

For example, when uploading photos for damaged items in a shipment, you might use:

• entity_type: shipment_item
• entity_id: A composite key such as shipmentId|sku|reasonCode|discrepancyId (e.g., 1RT823V93|SKU-001|DAMAGED|51076f94)

This pattern enables powerful bulk retrieval capabilities, such as querying all photos related to a specific shipment by searching for entity_type=shipment_item and an entity_id starting with the shipment ID.

Limitations

The following limitations exist for the service:

• Only shipment_item is currently supported as an entity_type.
• Supported upload formats: image/jpeg, image/png, image/webp, image/gif.
• HEIC/HEIF images must be converted to JPEG on the client device before upload.
• All processed images are converted to JPEG format regardless of the original input format.
• Upload URLs expire after 15 minutes.
• Download and thumbnail URLs expire after 1 hour.