Media Storage Service API documentation

Media Storage Service API documentation version 1.4.1

https://api.syniverse.com/mediastorage/v1

About Media Storage Service

The purpose of this specification is to describe the Media Storage Service (MSS) capabilities, core concepts, and API set. Media Storage Service is a collaborative file sharing service that enables batch services to exchange data in media files between customers and others services for processing.

File

The File resource refers to a data file within Media Storage Service that is associated to a unique file identifier named fileId..

Resource attributes:

  • file_id (string): Unique file identifier for the File

  • company-id (number): Company identifier

  • file_name (string): Name of the file (Filter Not implemented)

  • file_tags (string): File tags allow the files to be searched. A maximum of 5 tags allowed, each separated by comma(,) delimiter with optional spaces at start and end of tag (Filter Not implemented)

  • file_version (number): Version of the file metadata. Update operations must specify the extant version of the file

  • creation_time (date): Date/time when the file was defined.

  • file_retention_time (number): Time period for retention of file in days. Typically configured to 7 days

  • expire_time (date): Date/time when the file becomes expired. Determined by adding the file_retention_time to the creation_time.

  • app_name (string): Name of the application submitting the file

  • file_status (string): The file's creation status; e.g.,

    created (File is created but no upload has been performed), 

active (File upload is in progress), 

complete (File upload is complete), 

failed (File upload failed), 

deleted (File has been deleted).

The file_status is managed by the service 

(Filter Not implemented)

  • file_uri (string): URI for streaming the file content

  • file_size (number): The current size of the file on the store

  • file_fullsize (number): Size of file expected when upload is complete. Maximum allowed size is 200MB

  • file_compression_type (string): If compressed, specify the compression type.

get post

get

Returns the list of files associated with a customer. Additional filters can be used to narrow down the search result.

 
post

Create a new file returning the URI to subsequently stream the file.

 

Create a new file returning the URI to subsequently stream the file.

Body

Type: application/json

Form Parameters
  • file_name: (string)
  • file_tags: (string)
  • app_name: (string)
  • file_fullsize: (number)
  • file_compression_type: (string)

HTTP status code 200

successful operation

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Create Resource Response",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  }
}

HTTP status code 400

Bad Request. The request could not be understood by the server.

Possible Error Codes:

  • MSS1001 - file_name is mandatory - file_name is mandatory in file create operation
  • MSS1002 - file_fullsize is mandatory - file_fullsize is mandatory in file create operation
  • MSS1003 - file_fullsize is invalid - file_fullsize should be <= 200MB in file create operation
  • MSS1004 - file_tags is invalid - file_tags should be maximum of 5 tags in file create/update operations
  • MSS1007 - file_name is invalid - file_name cannot be more than 100 characters
  • MSS1008 - file_fullsize cannot be updated - file_fullsize is not updatable in file update operation
  • MSS1011 - file_version is mandatory - file_version is mandatory in file update operation
  • MSS1026 - Format error - One or more attributes has incorrect format or datatype in file create/update/delete/get operation
  • MSS1028 - int-companyid is mandatory - int-companyid is mandatory for all operations
  • MSS1030 - bearer token is mandatory - bearer token is mandatory

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 401

Unauthorized. The request requires user authentication.

Possible Error Codes:

  • MSS1029 - Unauthorize Access to Resource - bearer token and companyid not valid

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 402

Payment Required.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 403

Forbidden. The user does not have permission to access the specified resource.

Possible Error Codes:

  • MSS1012 - file_version is invalid - file_version is not correct in file update operation
  • MSS1014 - File is deleted - Deleted file cannot be updated in file update operation
  • MSS1015 - File is expired - Expired file cannot be updated in file update operation
  • MSS1016 - File is deleted - Deleted file cannot be updated in file delete operation
  • MSS1017 - File is expired - Expired file cannot be updated in file delete operation
  • MSS1018 - File is expired - Content cannot be uploaded for expired file in content uploaded operation
  • MSS1019 - File is deleted - Content cannot be uploaded for deleted file in content uploaded operation
  • MSS1020 - Content size exceeds file_fullsize - Content uploaded is larger than the file_fullsize in content uploaded operation
  • MSS1023 - File upload session is expired - Content uploaded is not allowed beyond the content upload expiry time of 1 day
  • MSS1024 - File is expired - Content cannot be downloaded for expired file in content download operation
  • MSS1025 - File is deleted - Content cannot be downloaded for deleted file in content download operation
  • MSS1027 - File upload not allowed - File upload attempted when file is already uploaded

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 404

"Not Found. The server has not found anything matching the Request-URI."

HTTP status code 409

Conflict. The request could not be completed due to a conflict with the current state of the target resource.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 412

Precondition Failed. The server does not meet one of the preconditions that the requester put on the request.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 429

Too Many Requests. The user has sent too many requests in a given amount of time.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 500

Server Error. An error has been encountered while processing this request.

Possible Error Codes:

  • MSS0001 - Internal server error - Report incident to system administrator

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 503

Server Unavailable.

get post delete

An individual file's details.

get

Returns the file information based on the fileid. File contents are not returned.

 
post

Update the file attributes.

 
delete

Removes the file and its contents

 

Returns the file information based on the fileid. File contents are not returned.

URI Parameters

  • file_id: required (string)

    This is the unique identifier of the file resource.

Query Parameters

HTTP status code 200

Successful operation

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "File",
  "type": "object",
  "properties": {
    "file_id": {
      "type": "string"
    },
    "company-id": {
      "type": "number"
    },
    "file_name": {
      "type": "string"
    },
    "file_tags": {
      "type": "string"
    },
    "file_version": {
      "type": "number"
    },
    "file_retention_time": {
      "type": "number"
    },
    "app_name": {
      "type": "string"
    },
    "file_status": {
      "type": "string"
    },
    "file_uri": {
      "type": "string"
    },
    "creation_time": {
      "type": "date"
    },
    "modified_time": {
      "type": "date"
    },
    "expire_time": {
      "type": "date"
    },
    "file_size": {
      "type": "number"
    },
    "file_fullsize": {
      "type": "number"
    },
    "file_compression_type": {
      "type": "string"
    }
  }
}

HTTP status code 400

Bad Request. The request could not be understood by the server.

Possible Error Codes:

  • MSS1001 - file_name is mandatory - file_name is mandatory in file create operation
  • MSS1002 - file_fullsize is mandatory - file_fullsize is mandatory in file create operation
  • MSS1003 - file_fullsize is invalid - file_fullsize should be <= 200MB in file create operation
  • MSS1004 - file_tags is invalid - file_tags should be maximum of 5 tags in file create/update operations
  • MSS1007 - file_name is invalid - file_name cannot be more than 100 characters
  • MSS1008 - file_fullsize cannot be updated - file_fullsize is not updatable in file update operation
  • MSS1011 - file_version is mandatory - file_version is mandatory in file update operation
  • MSS1026 - Format error - One or more attributes has incorrect format or datatype in file create/update/delete/get operation
  • MSS1028 - int-companyid is mandatory - int-companyid is mandatory for all operations
  • MSS1030 - bearer token is mandatory - bearer token is mandatory

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 401

Unauthorized. The request requires user authentication.

Possible Error Codes:

  • MSS1029 - Unauthorize Access to Resource - bearer token and companyid not valid

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 402

Payment Required.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 403

Forbidden. The user does not have permission to access the specified resource.

Possible Error Codes:

  • MSS1012 - file_version is invalid - file_version is not correct in file update operation
  • MSS1014 - File is deleted - Deleted file cannot be updated in file update operation
  • MSS1015 - File is expired - Expired file cannot be updated in file update operation
  • MSS1016 - File is deleted - Deleted file cannot be updated in file delete operation
  • MSS1017 - File is expired - Expired file cannot be updated in file delete operation
  • MSS1018 - File is expired - Content cannot be uploaded for expired file in content uploaded operation
  • MSS1019 - File is deleted - Content cannot be uploaded for deleted file in content uploaded operation
  • MSS1020 - Content size exceeds file_fullsize - Content uploaded is larger than the file_fullsize in content uploaded operation
  • MSS1023 - File upload session is expired - Content uploaded is not allowed beyond the content upload expiry time of 1 day
  • MSS1024 - File is expired - Content cannot be downloaded for expired file in content download operation
  • MSS1025 - File is deleted - Content cannot be downloaded for deleted file in content download operation
  • MSS1027 - File upload not allowed - File upload attempted when file is already uploaded

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 404

"Not Found. The server has not found anything matching the Request-URI."

HTTP status code 409

Conflict. The request could not be completed due to a conflict with the current state of the target resource.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 412

Precondition Failed. The server does not meet one of the preconditions that the requester put on the request.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 429

Too Many Requests. The user has sent too many requests in a given amount of time.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 500

Server Error. An error has been encountered while processing this request.

Possible Error Codes:

  • MSS0001 - Internal server error - Report incident to system administrator

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 503

Server Unavailable.

Update the file attributes.

URI Parameters

  • file_id: required (string)

    This is the unique identifier of the file resource.

Body

Type: application/json

Form Parameters
  • file_name: (string)
  • file_tags: (string)
  • file_version: (number)
  • app_name: (string)
  • file_fullsize: (number)
  • file_compression_type: (string)

HTTP status code 200

successful operation

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Create Resource Response",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  }
}

HTTP status code 400

Bad Request. The request could not be understood by the server.

Possible Error Codes:

  • MSS1001 - file_name is mandatory - file_name is mandatory in file create operation
  • MSS1002 - file_fullsize is mandatory - file_fullsize is mandatory in file create operation
  • MSS1003 - file_fullsize is invalid - file_fullsize should be <= 200MB in file create operation
  • MSS1004 - file_tags is invalid - file_tags should be maximum of 5 tags in file create/update operations
  • MSS1007 - file_name is invalid - file_name cannot be more than 100 characters
  • MSS1008 - file_fullsize cannot be updated - file_fullsize is not updatable in file update operation
  • MSS1011 - file_version is mandatory - file_version is mandatory in file update operation
  • MSS1026 - Format error - One or more attributes has incorrect format or datatype in file create/update/delete/get operation
  • MSS1028 - int-companyid is mandatory - int-companyid is mandatory for all operations
  • MSS1030 - bearer token is mandatory - bearer token is mandatory

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 401

Unauthorized. The request requires user authentication.

Possible Error Codes:

  • MSS1029 - Unauthorize Access to Resource - bearer token and companyid not valid

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 402

Payment Required.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 403

Forbidden. The user does not have permission to access the specified resource.

Possible Error Codes:

  • MSS1012 - file_version is invalid - file_version is not correct in file update operation
  • MSS1014 - File is deleted - Deleted file cannot be updated in file update operation
  • MSS1015 - File is expired - Expired file cannot be updated in file update operation
  • MSS1016 - File is deleted - Deleted file cannot be updated in file delete operation
  • MSS1017 - File is expired - Expired file cannot be updated in file delete operation
  • MSS1018 - File is expired - Content cannot be uploaded for expired file in content uploaded operation
  • MSS1019 - File is deleted - Content cannot be uploaded for deleted file in content uploaded operation
  • MSS1020 - Content size exceeds file_fullsize - Content uploaded is larger than the file_fullsize in content uploaded operation
  • MSS1023 - File upload session is expired - Content uploaded is not allowed beyond the content upload expiry time of 1 day
  • MSS1024 - File is expired - Content cannot be downloaded for expired file in content download operation
  • MSS1025 - File is deleted - Content cannot be downloaded for deleted file in content download operation
  • MSS1027 - File upload not allowed - File upload attempted when file is already uploaded

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 404

"Not Found. The server has not found anything matching the Request-URI."

HTTP status code 409

Conflict. The request could not be completed due to a conflict with the current state of the target resource.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 412

Precondition Failed. The server does not meet one of the preconditions that the requester put on the request.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 429

Too Many Requests. The user has sent too many requests in a given amount of time.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 500

Server Error. An error has been encountered while processing this request.

Possible Error Codes:

  • MSS0001 - Internal server error - Report incident to system administrator

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 503

Server Unavailable.

Removes the file and its contents

URI Parameters

  • file_id: required (string)

    This is the unique identifier of the file resource.

HTTP status code 200

successful operation

Body

Type: application/json

HTTP status code 400

Bad Request. The request could not be understood by the server.

Possible Error Codes:

  • MSS1001 - file_name is mandatory - file_name is mandatory in file create operation
  • MSS1002 - file_fullsize is mandatory - file_fullsize is mandatory in file create operation
  • MSS1003 - file_fullsize is invalid - file_fullsize should be <= 200MB in file create operation
  • MSS1004 - file_tags is invalid - file_tags should be maximum of 5 tags in file create/update operations
  • MSS1007 - file_name is invalid - file_name cannot be more than 100 characters
  • MSS1008 - file_fullsize cannot be updated - file_fullsize is not updatable in file update operation
  • MSS1011 - file_version is mandatory - file_version is mandatory in file update operation
  • MSS1026 - Format error - One or more attributes has incorrect format or datatype in file create/update/delete/get operation
  • MSS1028 - int-companyid is mandatory - int-companyid is mandatory for all operations
  • MSS1030 - bearer token is mandatory - bearer token is mandatory

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 401

Unauthorized. The request requires user authentication.

Possible Error Codes:

  • MSS1029 - Unauthorize Access to Resource - bearer token and companyid not valid

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 402

Payment Required.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 403

Forbidden. The user does not have permission to access the specified resource.

Possible Error Codes:

  • MSS1012 - file_version is invalid - file_version is not correct in file update operation
  • MSS1014 - File is deleted - Deleted file cannot be updated in file update operation
  • MSS1015 - File is expired - Expired file cannot be updated in file update operation
  • MSS1016 - File is deleted - Deleted file cannot be updated in file delete operation
  • MSS1017 - File is expired - Expired file cannot be updated in file delete operation
  • MSS1018 - File is expired - Content cannot be uploaded for expired file in content uploaded operation
  • MSS1019 - File is deleted - Content cannot be uploaded for deleted file in content uploaded operation
  • MSS1020 - Content size exceeds file_fullsize - Content uploaded is larger than the file_fullsize in content uploaded operation
  • MSS1023 - File upload session is expired - Content uploaded is not allowed beyond the content upload expiry time of 1 day
  • MSS1024 - File is expired - Content cannot be downloaded for expired file in content download operation
  • MSS1025 - File is deleted - Content cannot be downloaded for deleted file in content download operation
  • MSS1027 - File upload not allowed - File upload attempted when file is already uploaded

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 404

"Not Found. The server has not found anything matching the Request-URI."

HTTP status code 409

Conflict. The request could not be completed due to a conflict with the current state of the target resource.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 412

Precondition Failed. The server does not meet one of the preconditions that the requester put on the request.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 429

Too Many Requests. The user has sent too many requests in a given amount of time.

Possible Error Codes:

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 500

Server Error. An error has been encountered while processing this request.

Possible Error Codes:

  • MSS0001 - Internal server error - Report incident to system administrator

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Error Response",
  "type": "object",
  "properties": {
    "error_code": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  }
}

HTTP status code 503

Server Unavailable.

Copyright © 2017 Syniverse Technologies