Media Upload API Version 2

Version 2 of the Media Upload API allows you to not only upload a media file to OpenMarket's Content Management System (CMS), but also to manage the file. With version 1 of the API, you could only upload a media file, which would then automatically be removed from the CMS after 30 days. You could not extend the expiration date. With version 2, media files are still stored in the CMS for a default 30 days, but you can now extend that date up to one (1) year out, retrieve information about the file, or to delete it from the CMS.

With the version 1 API you were required to pass the mimeType and file size in the upload request. For version 2, this information is not required. You simply need to use the POST method to upload a Base-64 encoded media file and an optional expiration date.

The API supports the following methods:

• POST - Upload a media file.
• GET - Retrieve information about the file you've uploaded.
• PUT - Update the expiration date.
• DELETE - Remove the media file from the CMS.

Before uploading any media, you must have a valid account and permission to upload your images. Images must be encoded to Base64 and the request submitted using JSON with basic authentication.

Quick facts

Request URL Definition

Production

{Method} https://rcs.openmarket.com/cms/v2/content

Pre-production

{Method} https://rcs.openmarket.com/cms/v2/content

Authentication

For any of the methods, the following authentication is required.

Header example

Authorization:  Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type:application/json

Note: JSON is currently the only supported application type.

Upload a media file

Upload a media file using the POST method. A successful request uploads the media file, creates a request ID and sets a default expiration date unless otherwise specified in the request. The returned request ID can then be used to manage the uploaded file.

POST request URL

POST https://rcs.openmarket.com/cms/v2/content

Example POST request body

{
  "content" : "iVBORw0KGgoAAAANSUhEUgAAAuQAAADnCAMAAABhcbPQAAAABGdBTUEAALGP...",
  "expirationDate": "2019-08-01"
}

The POST request body is composed of the following:

POST Response

A successful upload returns a response header and body.

POST response header

The response header contains the request ID, which is used to identify the media in other tasks, as well as the URL of the uploaded file.

X-Request-Id: 053-8a767024-1243-4809-836e-b83896a37b6a
Location: https://s3-us-west-1.amazonaws.com/openmarket-us-west-1-rcs-cms-uploads-test/f6ee3cb/d192591a-3aaa-4f40-8a55-1653fa3a9c44

POST response body

The body returns information about the uploaded file, including the file identifier, default expiration date, file size, and content type.

{
    "id": "8b43d7ae-9bfc-417d-bd85-64205a2428d4",
    "expirationDate": "2020-01-22T00:00:00Z",
    "size": 334429,
    "contentType": "image/jpeg"
}

Note: Make note of the ID. This ID is used to make any updates to the file, such as updating the expiration date or deleting the file from the CMS.

Note: If you upload a media file that already exists in the CMS, the newer file is not uploaded. Instead, a 302 response is returned indicating that the file already exists. The request ID and file location are returned in this response.

Response codes

The following codes can be returned for a media file upload.

Response codes

{
"id": "78994649-c8b7-427e-848b-18e6ff162996",
"expirationDate": "2019-06-24T00:00:00Z",
"size": 334429,
"contentType": "image/jpeg",
"location": "https://...."
}

{
    "invalidReasons": [
        "Missing IDS account ID",
        "Supplied file size does not match content"
    ],
    "valid": false
}

Get media file information

Use the GET method to retrieve information about a previously uploaded file. To use the method, you must pass the request ID of a file currently stored in the CMS. This method uses the Authentication parameters described above.

GET request URL

GET https://rcs.openmarket.com/cms/v2/content/<id>

For example,

GET https://rcs.openmarket.com/cms/v2/content/053-8a767024-1243-4809-836e-b83896a37b6a

GET response header and body

A successful GET request returns a response header and body.

GET response header

The following shows a header example for a successful GET request.

X-Request-Id: 053-8a767024-1243-4809-836e-b83896a37b6a
Location: https://s3-us-west-1.amazonaws.com/openmarket-us-west-1-rcs-cms-uploads-test/f6ee3cb/d192591a-3aaa-4f40-8a55-1653fa3a9c44

GET response body

The body contains details about the uploaded file:

{
    "id": "8b43d7ae-9bfc-417d-bd85-64205a2428d4",
    "expirationDate": "2020-01-22T00:00:00Z",
    "size": 334429,
    "contentType": "image/jpeg",
    "location": "https://s3-us-west-1.amazonaws.com/openmarket-us-west-1-rcs-cms-uploads-test/f6ee3cb/d192591a-3aaa-4f40-8a55-1653fa3a9c44"
}

Note: If you don't remember the ID, and you have the current file available, try re-uploading that file using the POST method. Since the file already exists in the CMS, the upload response will instead return a 302 response code along with the ID of the file. You can then note that ID.

GET response codes

• A successful GET returns an HTTP 200 OK response, indicating success.
• For any error in getting file information, an HTTP 404 Not Found response is returned.

Update the media expiration date

Use the PUT method to update the expiration date of a media file in the CMS. The request body will contain the ID of the file to update and the new expiration date. This method uses the Authentication parameters described above.

PUT request URL

PUT https://rcs.openmarket.com/cms/v2/content

Example PUT request body

{
    "id": "f5554169-3b5b-4b47-9176-71619bc0cf0e",
    "expirationDate": "2020-05-31"
}

PUT response codes

• A successful PUT returns an HTTP 200 OK response, indicating success.
• For any error in updating the file, an HTTP 404 Not Found response is returned.

Delete a media file

Use this method to remove a media file from the CMS by passing the request ID of the file to delete in the URL. This method uses the Authentication parameters described above.

DELETE request URL

DELETE https://rcs.openmarket.com/cms/v2/content/<id>

For example,

DELETE https://rcs.openmarket.com/cms/v2/content/d5bc5537-6924-4022-8dfc-e479ccdbb6

DELETE response codes

• A successful DELETE returns an HTTP 200 OK response, indicating success.
• For any error in deleting the file, an HTTP 404 Not Found response is returned.