The purpose of this user guide is to describe how to get started with the Media Storage Service and is intended to provide a high level understanding of the required components for the file upload and download process.
Prerequisites
Before you can access Media Storage Service you must complete the listed items in the following order:
- Create a Company Environment in the Syniverse Developer Community
- Subscribe to the Media Storage Service
- Application created in Syniverse Developer Community
- Application resources have Media Storage Service (MSS) turned ON
Related Services
Media Storage Service is currently used to provide the services for:
- Phone Number Verification Scrub Job
- Phone Number Verification Monitoring Jobs
Key Concepts
The following concepts are central to understanding the Media Storage Service:
File Storage: Every file resource on MSS consists of file metadata and file content. Each file is identified by a unique file identifier named file_id. Typical file management REST APIs are like CRUD APIs that are used to create a file (metadata creation), update file metadata, delete a file, read a file based on the file_id, list files or search files based on file tags or other criteria. File content may be uploaded and downloaded to and from MSS using key resource references like the file_id or file_uri in the REST APIs. This is realized through a simple HTTP POST/GET protocol where the body of the HTTP method is a stream of media or content bytes. Note: The int-companyid field needs to be provided as a HTTP header in HTTP POST for file content upload requests and HTTP GET file for content download requests.
File Upload: File content is uploaded using a POST operation to the content resource. The content type is specified as an application/octet-stream, and the body of the request should be raw content bytes.
File Download: File content is downloaded using a GET operation to the content resource. The response content type header is application/octet-stream and response body will contain the raw content bytes.
File Management: The Media Storage Service provides the following operations on files:
- Define new file metadata
- Modify file metadata
- Upload file content
- Download file content
- Query file metadata
- Delete file(s)
Content Management: Content may be uploaded to a ready made file by POST operation using the file_id resource identifier. Content may be downloaded using GET operation using the file_id resource identifier
Flow of Service
This section contains more details on the flow of service when creating a file, uploading file contents and downloading a file.
Creating a File
The first step in the flow is to create a file in the system. This step is for creating metadata to be associated with a file upload. Unless specifically stated, the below fields are only labels and control no underlying behavior.
| Field | Description |
|---|---|
| file_name | Human readable non-unique name for this file. This is provided for user's convenience and has no meaning in MSS. |
| file_tags | Tags can be set by Customer to track different files. JSON format array of tags associated with the media file. File tags may be used as search keys. |
| app_name | Identifies the application that uploaded the file. |
| file_fullsize | Expected size of file that will be uploaded in bytes. Attempting to upload a file larger that this value will result in a validation failure on the file upload service. |
| file_compression_type | Content compression method. Example: gzip |
| file_status | Status
of this file. Possible values are:
|
Uploading File Contents
In the file creation response is a “file_uri” field. POST a file or text to this uri to upload content for the related metadata.
Downloading a File
...Alternatively, performing a GET on “file_uri” will download the file content.
An example API call can be seen from this page.