Version 8.3.8

Getting Started With The PUT API

Functions described in this document are invoked by passing requests to this URL:

{base url}/ws/{function_name}/api/{api_version}?method=put

Processing the request JSON

The request must be json.

// generate the URL. Can also be https
$url = "http://de.piksel.tech/ws/{function_name}/api/{api_version}"?method=put;

*Use method get param only if the client does not support PUT method to submit data. (some flash clients). Use PUt http header to send request data.

// base 64 encode the request:
$request = "{json request}"

// Capture response with CURL
$handle = curl_init();
curl_setopt( $handle, CURLOPT_URL, $url );
curl_setopt( $handle, CURLOPT_POSTFIELDS, array("request" => $request) );
curl_setopt( $handle, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec( $handle );
curl_close( $handle );

Formatting The JSON Request

The body tag of the request JSON is <request></request>, containing 3 main sections:

<authentication>	User authentication data used to authorize request
<header>	Header section specifies the API version to be used when calling a given function
<{API Function}>	Specifies which function to call and contains relevant parameters

Authentication

Contains the following fields

<user_token>	Contains the user token string value, returned by the login function successful response. Should be saved for subsequent requests within the session
<client_token>	<client_token> Client UUID which can be found by navigating to Client Preferences -> API Consumer Accounts
<app_name>	The web application name that calls the web services.
<app_token>	API token constant string value
<no_cache>	Boolean value to specify whether authentication will done freshly or from cache.

An example of the authentication section

{
    "request": {
        "header": {
            "header_version": 1,
            "api_version": "4",
            "no_cache": true
        },
        "login": {
            "username": "",
            "password": "",
            "static_login": false
        }
    }
}

Header

Contains the following fields

<header_version>	Not used for the moment – empty value
<api_version>	The API version number to be used – numeric value

An example of header section:

 "header": {
            "header_version": 1,
            "api_version": "4",
            "no_cache": true
        }

API Function Body

<{API function name}>

The API function name to call. This tag has no attributes and contains different child tags (or does not contain any), depending on the API function called, ie. It's content is function specific and described in detail for each function in the Post API Function Docs.

Following is an example PUT request document for calling the function ws_asset :

"ws_asset": {
      "assetid": 980457,
      "title": "title",
      "description": "description",
      "date_start": "2014-03-05T13:15:30Z",
      "date_end": "2024-11-05T13:15:30Z",
      "metadatas": {
        "metaname1": "metaname1value"
      },
      "isHidden": 1,
      "isPublished": 1,
      "youtubePublishable": true,
      "tags": "",
      "referenceId": "dcsddsvdv",
      "geoFilterId": 500
    }

Wrapping It Up

Here is a complete example using all of three of the previously discussed sections.

{
  "request": {
    "authentication": {
      "app_token": "7cd207c2-6808-11e3-b865-22000a8a28ea",
      "client_token": "d4c1b92c0acb102ba3e10015c5f061d1",
      "user_token": "f277cb9d46e45f67f44de949cdde110f"
    },
    "header": {
      "header_version": 1,
      "api_version": "5",
      "no_cache": true
    },
    "ws_asset": {
      "assetid": 980457,
      "title": "title",
      "description": "description",
      "date_start": "2014-03-05T13:15:30Z",
      "date_end": "2024-11-05T13:15:30Z",
      "metadatas": {
        "metaname1": "metaname1value"
      },
      "isHidden": 1,
      "isPublished": 1,
      "youtubePublishable": true,
      "tags": "",
      "referenceId": "dcsddsvdv",
      "geoFilterId": 500
    }
  }
}

Response

The response data returned by Piksel Digital Enterprise API v5.0 is also JSON with base node named <response> and contains a {function_name}_response tag for the called function. It contains a status section and different child tags, depending on the API function called. The status section can contain either success or failure tags:

Success

Tag returned in case of successful execution of an API function. It has no attributes and contains the following child tags:

<code>	Status code returned by the API function, integer value
<message>	Some specific message set from the function, string value
<details>	Additional details, if available, also function specific
<dtstamp>	Date/time stamp in format YYYY-MM-DD HH:MM:SS, string value

An example of successful tag:

  "success": {
      "code": 501,
      "message": "Asset Saved/Updated",
      "details": ""
    }

Failure

Tag returned in failure case from the API function called. It contains no attributes and the following child tags

<code>	Status code returned by the API function, integer value
<reason>	Some specific message set from the function, reason for the failure, string value
<details>	Additional details, if available, also function specific
<severity>	Severity of the function failure, string value
<dtstamp>	Date/time stamp in format YYYY-MM-DD HH:MM:SS, string value

An example of a failure tag:

"failure": {
            "code": 102,
            "reason": "Invalid app token.",
            "details": "",
            "severity": "Error",
            "dtstamp": "2014-04-14 14:20:44"
        }

Example of full failure response document returned by login API function:

{
    "response": {
        "failure": {
            "code": 102,
            "reason": "Invalid app token.",
            "details": "",
            "severity": "Error",
            "dtstamp": "2014-04-14 14:20:44"
        }
    }
}

And now a complete successful response document from the same function:

{
  "response": {
    "success": {
      "code": 501,
      "message": "Asset Saved/Updated",
      "details": ""
    },
    "updateMediaAssetResponse": {
      "assetid": 980457,
      "title": "title",
      "dateadd": "2012-04-30T17: 52: 41Z",
      "datemod": "2012-04-30T17: 55: 25Z",
      "defaultThumb": "3388204",
      "description": "description",
      "tags": "",
      "isActive": 1,
      "isHidden": 0,
      "posterThumb": "",
      "geoFilterId": 0,
      "uuid": "1a747376",
      "isPublished": 1,
      "date_start": "2014-03-05T13:15:30Z",
      "date_end": "2024-11-05T13:15:30Z",
      "youtubePublishable": 1,
      "thumbnailUrl": "http: \/\/player-qa.piksel.tech\/thumbs\/aid\/w\/h\/t1335808525\/980457.jpg",
      "thumbRel": "\/thumbs\/aid\/w\/h\/t1335808525\/980457.jpg",
      "assetType": "video",
      "asset_type": "video",
      "assetFiles": [

      ],
      "m3u8iPadURL": "",
      "m3u8iPhoneURL": "",
      "m3u8AndroidURL": "",
      "httpSmil": "",
      "hdSmil": "",
      "rtmpSmil": "",
      "associatedLinks": [

      ],
      "captions": [

      ],
      "AssociatedFiles": [

      ],
      "metadatas": {
        "metaname1": {
          "0": "",
          "value": "metanme1value",
          "type": "text"
        }
      }
    }
  }
}