Getting Started with the Platform API

• Piksel Developer
• Concepts
• Getting Started with the Platform API

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.pikselpalette.com

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.pikselpalette.com/services/$ACCOUNT_NAME"

An example response is:

{
  "services": [
    {
      "owner": "root",
      "name": "identity",
      "title": "Identity Service",
      "location": "https://identity-euw1shared.pikselpalette.com"
    },
    {
      "owner": "root",
      "name": "console",
      "title": "Console Service",
      "location": "https://console-euw1shared.pikselpalette.com"
    },
    {
      "owner": "root",
      "name": "registry",
      "title": "Registry Service",
      "location": "https://registry-euw1shared.pikselpalette.com"
    },
    {
      "owner": "root",
      "name": "metadata",
      "title": "Metadata Service",
      "location": "https://metadata-euw1shared.pikselpalette.com"
    },
    {
      "owner": "root",
      "name": "feed",
      "title": "Feed Service",
      "location": "https://feed-euw1shared.pikselpalette.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.pikselpalette.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.pikselpalette.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.pikselpalette.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:

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