Base URL

The medialoopster Web API Root is /api/ which is appended to the end of the medialoopster URL.

In the sample calls throughout this documentation we use medialoopster-url as a placeholder for the medialoopster URL:

http://medialoospter-url/api/

Versioning

medialoopster Web API uses Accept Header Versioning Scheme. To request a specific API version, the version number must be added to the HTTP Header Accept:

Accept: application/json; version=1

The use of the header addition is optional. If the version is missing, it defaults to the latest version available.

Access Test

medialoopster Web API provides a Ping-like resource to test if the API is accessible.

curl -X GET http://ml-develop.local/api/ping/

Authentication

Unless otherwise noted, all medialoopster Web API requests require an authentication token in the form of "Token xxxxx" (where xxxxx is the generated token). The token can be acquired by any registered user. The authentication token must be provided through the HTTP Header Authorization.

In case the server cannot read the authentication token (i.e. the token is missing, wrong format) the server responds with:

401 - Unauthorized

{
  "errors": [
    {
      "status": "401",
      "code": "authentication_failed",
      "detail": "Invalid token.",
      "title": "Authetication has failed"
    }
  ]
}

{
  "token": "eb2b3d60297859d1cb995ca65f508ef5798545dd"
}

{
  "errors": [
    {
      "status": "400",
      "code": "authorization",
      "meta": {
        "type": "non_field"
      },
      "detail": "Unable to log in with provided credentials.",
      "title": "Validation Error"
    }
  ]
}

curl -X POST http://medialoopster-url/api/token-auth/ \
  -d username=joan%40nachtblau.tv \
  -d password=joanspassword

Content-Type

medialoopster Web API uses JSON for data formatting. Unless otherwise noted, all responses in this documentation are of the content type application/json (requires Accept header to be set to "application/json", see Versioning).

Aside from application/json medialoopster Web API also supports application/x-www-form-urlencoded for data sent by the client.

Pagination

When a resource collection is requested the returned data only contains a limited set of objects. To retrieve the remaining objects or a different subset of objects, the API client can use the query parameters limit and offset. By default the returned set of objects is limited system wide to 25 objects with a limit cap at 100 objects. Both values can be changed through system settings.

In addition medialoopster Web API supports Link Based Header Pagination to help the API client to navigate through the collection. If applicable the possible links are next, prev, last and first like in the following example:

Link: 
 <http://medialoopster-url/api/videoassets/?limit=100&offset=2600>; rel="next", 
 <http://medialoopster-url/api/videoassets/?limit=100&offset=2400>; rel="prev", 
 <http://medialoopster-url/api/videoassets/?limit=100&offset=5100>; rel="last", 
 <http://medialoopster-url/api/videoassets/?limit=100>; rel="first"