Advanced API¶

Introduction¶

The Dailymotion Graph API is designed to make it really easy to get data for individual objets and lists of objects. If your application needs more control over the latency and caching, the Advanced API protocol is here to help you.

To enable this, the Advanced API allows to pass instructions for several opration in a single HTTP request. The protocol also provide a better caching control mechanism.

Call a Method¶

To call a method, all you need is a JSON object with the 2 following parameters POSTed on the https://api.dailymotion.com URL endpoint:

• call - The method + resource URI (ex: GET /me, POST /videos). If the method is omited, the GET method is implied.
• args - A JSON object with named arguments to send to the method (ex: {"title": "My New Title"}).

Here is an example request:

{
  "call": "POST /video/xa3krd9",
  "args":
  {
    "title": "A Title",
    "tags": ["a tag", "another tag"]
  }
}

The following parameters may also be added:

• id - An opaque string or number that will be returned in the response
• etag - An entity tag used to conditionally call the method (see Cache Management later in this document for more info)

Response¶

A response is a JSON object with two mutually exclusive parameters:

• result - Contains the result of the method on success
• error - Contains information about an error returned by the method

A successful response is a JSON object with a result key containing another JSON object. There is two kinds of response: dict and list.

The dict response type is a single level JSON object with key/values pairs. Values can be of type string, number, boolean or array. Dates are stored as number and are expressed as number of seconds since the UNIX Epoch (January 1 1970 00:00:00 GMT).

Example of a dict response:

{
  "result":
  {
    "title": "A title",
    "tags": ["a tag", "another tag"],
    "created_time": 1286368714
  }
}

The list response type is used when a list of objects is requested. It consist of a dictionary with 4 keys:

• page - The current page number starting at 1
• limit - The number of items returned per page
• has_more - A boolean value indicating if there are more items on the next page
• list - An array containing a list of dict, all the same set of keys. Values can be of type string, number, boolean or array. Dates are stored as number and are expressed as number of seconds since the UNIX Epoch (January 1 1970 00:00:00 GMT).

Example of a list response:

{
  "result":
  {
    "page": 1,
    "limit": 10,
    "has_more": false,
    "list":
    [
      {
        "title": "A cool video",
        "tags": ["a tag", "another tag"],
        "created_time": 1286368714
      },
      {
        "title": "My amazing video",
        "tags": ["tag1"],
        "created_time": 1286376485
      },
      {
        "title": "Yet another astonishing video",
        "tags": ["foo", "bar"],
        "created_time": 1286356045
      }
    ]
  }
}

Sometimes a method may return an error. In such case, the JSON returned contains an error instead of a result key with a JSON object as value. An error object contains 2 keys:

• code - The numeric error code for the error (see Error Codes)
• message - A string containing a descriptive message about the error in English

Example of an error response:

{
    "error":
    {
      "code": 403,
      "message": "Insufficient scope for `delete' method, scope required: delete"
    }
}

Multi-Call¶

When latency is important (on mobile applications for instance), it is possible to perform up to 10 actions in a single HTTP request. Each actions are put in a JSON array. The responses will be returned in a JSON array in the same order as they where requested.

Here is an example of multi-call request:

[
  {
    "call": "/auth"
  },
  {
    "call": "/video/x1k2",
    "args":
    {
      "fields": ["title", "thumbnail_url", "owner.screenname"],
    },
    "id": "an opaque id"
  },
  {
    "call": "/invalid/ressource",
  }
]

And then the resulting responses:

[
  {
    "result":
    {
      "scope": ["read"],
      "roles": [],
      "user_id": "xk2k3",
    }
  },
  {
    "result":
    {
      "title": "A title",
      "thumbnail_url": "http://...",
      "owner.screenname": "John Do"
    },
    "id": "an opaque id",
    "cache":
    {
      "pubic": true,
      "maxage": 900,
      "etag": "hAkyy5oqCLW6Xt5hHe-YPg"
    }
  },
  {
    "error":
    {
      "code": 501,
      "message": "Unsupported method: /invalid/call"
    }
  }
]

Authorization¶

The Dailymotion API uses OAuth 2.0 for authorization. Check out the authentication guide for the details of the Dailymtion’s OAuth 2.0 implementation.

At a high level, using OAuth 2.0 entails getting an access token for a Dailytmotion user via a redirect to Dailymotion. After you obtain the access token for a user, you can perform authorized requests on behalf of that user by including the access token to the API endpoint URL like this:

https://api.dailymotion.com?access_token=<ACCESS_TOKEN>

Or preferably by adding the Authorization HTTP header like this:

curl -d '...JSON...' -H 'Authorization: OAuth <OAUTH_TOKEN>' https://api.dailymotion.com

The steps to obtain an access token are:

• Register your application to get an API Key and a secret. Your Dailymotion API Key is your client_id and your Dailymotion API secret is your client_secret.

• Redirect the user to https://api.dailymotion.com/oauth/authorize with your client_id and the redirect_uri. The redirect_uri parameter needs to begin with the Callback URL you assigned to you API Key:

  https://api.dailymotion.com/oauth/authorize?
      client_id=<API_KEY>&
      redirect_uri=http://www.example.com/oauth_redirect

• After the user authorizes you application, we redirect the user back to the redirect URI you specified with a verification string on the argument code, which can be exchanged for an oauth access token. Exchange it for an access token by fetching https://api.dailymotion.com/oauth/token. Pass the exact same redirect_uri as in the previous step:

  https://api.dailymotion.com/oauth/token?
      grant_type=authorization_code&
      client_id=<API_KEY>&
      client_secret=<API_SECRET>&
      redirect_uri=http://www.example.com/oauth_redirect&
      code=<AUTHORIZATION_CODE>

• Use the access token returned by the request above to make API calls.

Cache Management¶

The Advanced Dailymotion API defines a rich set of caching directives. Caching is the best way to reduce latency in your application by reducing or even removing the size of data to be transferred.

{
  "result":
  {
    ... method result payload ...
  },
  "cache":
  {
    "namespace": "aRw9pEGA77rsgJ417yT3cA",
    "public": false,
    "maxage": 900,
  }
}

{
  "result":
  {
    ... method result payload ...
  },
  "cache":
  {
    "namespace": "aRw9pEGA77rsgJ417yT3cA",
    "public": false,
    "maxage": 900,
    "etag": "hAkyy5oqCLW6Xt5hHe-YPg",
  }
}

{
  "etag": "hAkyy5oqCLW6Xt5hHe-YPg",
  "call": "POST /videos"
}

{
  "cache":
  {
    "namespace": "aRw9pEGA77rsgJ417yT3cA",
    "public": false,
    "maxage": 900,
    "etag": "hAkyy5oqCLW6Xt5hHe-YPg",
  }
}

{
  "result":
  {
    ... method result payload ...
  },
  "cache":
  {
    "invalidates": ["aRw9pEGA77rsgJ417yT3cA", "CICtFj-YhnrBHD9fE2wS9g"]
  }
}