Overview

Schema

  • All API access must be over HTTPS.
  • All data is sent and received as JSON.
  • Blank fields are included as null instead of being omitted.
  • All timestamps are returned in UTC and ISO-8601 format: YYYY-MM-DDTHH:MM:SSZ

Resource Methods

List items

GET /resource

Returns a list of matching resources. Context-specific query parameters can be used to filter or sort the list. Pagination applies here.

Get an item by ID

GET /resource/(id)

Returns a single item.

Add a new item

POST /resource

The values for the item are specified in the request body in JSON.

Edit an item

PUT /resource/(id)

Replace the item with the given complete set of parameters.

PATCH /resource/(id)

Update the item with the given parameters and leave omitted parameters unchanged.

Delete an item

DELETE /resource/(id)

The response will be 204 No Content.

HTTP Status Codes

Generally, successful requests will respond with 200 OK.

Redirects

301 Moved Permanently
The URL you requested has changed, and the client should request the new URL next time.
302 Found
This is a temporary redirect. The client should not cache the redirect location.

Validation Errors

400 Bad Request
The request is malformed, or the JSON body could not be decoded. Depending on the severity of the error, this may include a JSON body with a message parameter.
422 Unprocessable Entity

The request was formatted correctly but contained some invalid values.

{
   "message": "Invalid values",
   "errors": [
   ]
}

Retryable Errors

500 Internal Server Error
Something went wrong and the request can be retried.
502 Bad Gateway
Something went wrong and the request can be retried.
503 Service Unavailable

Something went wrong and the request can be retried.

Note

This status code will also be returned for all write operations when MediaCore is in read-only mode. See Read-only Mode for more information.

In the event of any of these errors, we suggest that you employ an exponential backoff algorithm to retry your request periodically.

retry_delay_in_seconds = 5 * (2 ** n)  # while 0 < n < 15

Read-only Mode

During scheduled maintenance, or should unforseen issues arrise, MediaCore may be temporarily placed into a read-only mode. Read requests to the API (GET, HEAD) will be continue to function normally while write requests (POST, PUT, DELETE) will return a 503 Service Unavailable response like this:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8

{
  "message": "Write operations are currently disabled."
}

If you receive this response, you should retry the request periodically.

Cross Origin Resource Sharing

Cross-domain Ajax requests are supported via CORS, but only from domains that you have whitelisted. You can whitelist as many domains are you like by going to your site’s Admin > Settings > Extensions panel and adding a domain to the list of CORS origins.

You can read more about about CORS here:

Note

We have no plans to support JSONP because CORS is now supported by all modern browsers.

Upload Protocols

All file uploads in MediaCore follow the same basic workflow. First, the client requests an upload URL from the MediaCore API. In the response, MediaCore provides the client with details for one or more upload protocols that it can use to upload the file. The client then chooses its preferred protocol and begins the upload process.

For a description of the upload protocols see Upload Protocols