Welcome to Piksel Video Platform API!

Services in the Piksel Video Platform expose an API which can be used to build your own video solution or as part of a prepackaged solution such as Fuse or Showcase.

This guide covers:

  • What do I need to start interacting with the APIs?
  • How to authenticate and become authorised to use the APIs?
  • How do I discover what services are available to me?
  • How do I learn what those services APIs are?

Prerequisites

In order to make use of the APIs, the following are needed:

  • A suitable client, such as curl or our Client SDKs in javascript or java
  • An account on the video platform (please speak with your account manager if you need more details)
  • Your app’s client id and secret
  • Optionally, your own username and password if you are authenticating as yourself through your app
  • The location for the Registry Service, usually https://registry-euw1shared.sequoia.piksel.com
Security

The following examples make use of shell environment variables to store values for later use. This includes credentials and other sensitive information. This approach is used for readability and simplicity - readers are advised that they should take all necessary precautions to ensure that such information remains secure as deemed appropriate by their organisations security standards.

Service Discovery

The first step when interacting with the Video Platform APIs is to discover the locations of services.

Assuming that your account name is stored in an environment variable called ACCOUNT_NAME, then make the following request:

curl -v -X GET "https://registry-euw1shared.sequoia.piksel.com/services/$ACCOUNT_NAME"

An example response is:

{
  "services": [
    {
      "owner": "root",
      "name": "identity",
      "title": "Identity Service",
      "location": "https://identity-euw1shared.sequoia.piksel.com"
    },
    {
      "owner": "root",
      "name": "console",
      "title": "Console Service",
      "location": "https://console-euw1shared.sequoia.piksel.com"
    },
    {
      "owner": "root",
      "name": "registry",
      "title": "Registry Service",
      "location": "https://registry-euw1shared.sequoia.piksel.com"
    },
    {
      "owner": "root",
      "name": "metadata",
      "title": "Metadata Service",
      "location": "https://metadata-euw1shared.sequoia.piksel.com"
    },
    {
      "owner": "root",
      "name": "feed",
      "title": "Feed Service",
      "location": "https://feed-euw1shared.sequoia.piksel.com"
    }
  ]
}

Authentication & Authorisation

The system makes use of OAuth 2.0 as an authorization framework to manage access to protected resources.

Authentication can be performed as the app itself, using just it’s owner, client id and client secret or as a user by additionally supplying the user’s domain, username and password.

Preparing your client credentials

Client credentials must be concatenated with a colon separator and base64 encoded.

Assuming owner is owner, client id is your_client_id and client secret your_secret, then this can be done using:

export ENCODED_CLIENT_CREDS=$(echo -n 'owner.your_client_id:your_secret' | openssl base64)

Authorisation as an App

Apps authenticate using the OAuth 2 client credentials grant. This returns an access token that can be supplied to subsequent requests as a bearer of those permissions.

The encoded credentials are passed into the authorisation request like so:

curl -v -X POST "https://identity-euw1shared.sequoia.piksel.com/oauth/token" \
        -H "Authorization: Basic $ENCODED_CLIENT_CREDS" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "grant_type=client_credentials"

Authorisation as a User

User authenticate through an App using the OAuth 2 resource owner password credentials grant. This returns an access token that can be supplied to subsequent requests as a bearer of those permissions.

Assuming the users credentials are domain test, username test-user and password itsasecret, then an authorisation request would be:

curl -v -X POST "https://identity-euw1shared.sequoia.piksel.com/oauth/token" \
        -H "Authorization: Basic $ENCODED_CLIENT_CREDS" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "grant_type=password&username=test\test-user&password=itsasecret"

Authorisation response

Successful authentication requests will result in a response of the following form containing the access token that can be used for subsequent API requests:

{
  "token_type": "bearer",
  "access_token": "YOUR_TOKEN",
  "expires_in": 3600
}

Further examples assume that the access token is stored in an environment variable called ACCESS_TOKEN.

Verify access token

An access token can be verified to check what permissions it has. Use a GET request like so:

curl -v -X GET "https://identity-euw1shared.sequoia.piksel.com/oauth/token" \
        -H "Authorization: Bearer $ACCESS_TOKEN"

An example response is:

{
  "tokenType": "bearer",
  "accessToken": "0de61a207672b8e5167592c895bafb3722846441",
  "expires": "2016-09-18T23:22:46.499Z",
  "dynamic": false,
  "clientId": "your_client_id",
  "directoryRef": "root:client",
  "userRef": "root:your_client_user_ref",
  "userType": "service",
  "permissions": [{
    "tenant": "account1",
    "actions": ["service:resource:read", "service:resource:write"]
  }, {
    "tenant": "account2",
    "actions": ["service:resource:read", "service:resource:write"]
  }]
}

Session Duration

The standard duration of an access session is 4 hours. On expiry, a new token must be obtained using the same method above if you wish to continue accessing the API.

Accessing Services

Now that you have both the location of all available services for your account and an access token, you can interact with additional services as necessary. All services in the Piksel Video Platform conform with the same REST API specification, ensuring consistent interaction and a low barrier to adoption regardless or whether one, many or all services are utilised.

For more information about the services available, see products.

Rate limits (coming soon)

REST APIs are subject to a limit on how many calls can be made in a given period in order to ensure fairness, protect from overloading, and maintain high quality of service to many clients.

The context of each rate limit is typically on the basis of:

  • per access session
  • per service
  • per minute

You can check the returned HTTP headers of any API request to see your current rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1471557325000

Errors

The Video Platform APIs use the following error codes:

Code Meaning
400 Bad Request
Your request is invalid.
401 Unauthorized
Your access token is not authorised to access the resource.
403 Forbidden
You need to authenticate to access the resource.
404 Not Found
The specified resource could not be found.
405 Method Not Allowed
You tried to access a resource with an invalid HTTP method.
406 Not Acceptable
You requested a format that isn’t supported.
412 Precondition Failed
You tried to store a resource but the version has changed.
415 Unsupported Media Type
You tried to store a resource with a representation (content-type) that isn’t supported.
422 Unprocessable Entity
You tried to PATCH a resource but the changes could not be applied.
429 Too Many Requests
You have exceeded the limits allowed for your account. Look at the rate limit headers to understand which limit.
500 Internal Server Error
We had a problem with the service. Please try again later.
502 Bad Gateway
We had a problem with the service due to an upstream dependency. Please try again later.
503 Service Unavailable
We’re temporarially offline for maintanance. Please try again later.

When an error occurs, the response body should be application/json and have the following attributes:

  • statusCode - the http status code, e.g. 404
  • error - the http status reason phrase, e.g. Not Found
  • message - [optional on 400] human readable description of the error reason
  • validation - [optional on 400] an object providing details of the validation failure