Tuesday 4 April 2017

PHP and TACTIC Rest API

TACTIC 4.6 just introduced a new generic REST API which implements most of the TACTIC API.  This opens up the TACTIC API to almost all programming languages.   There are still some advantages to using the client side libraries for Python and Javascript as there is some custom convenience and logic written in the client side libraries.  However, for many important operations, the rest API is sufficient.  This is especially useful when integrating TACTIC with such platforms as WordPress or Drupal or AngularJS.

Since the TACTIC API functionality is very deep, the first REST implementation has been to only support POST requests.   This provides the access to all of the arguments of the API methods without the inconvenient limitation of using a URL to provide all of the arguments to methods.

The following example will made use of the PHP curl functionality wrapped up in a convenience function.  It is assumed that you already have a login ticket.  A login ticket is any non-expired entry in the "ticket" table in the "sthpw" database.

The following function wraps up all the settings needed to access a TACTIC server:

function executeREST($data) {
    $server = "http://tactic.server.com";
    $login_ticket = "8f096a8359bbc355943f93545684b90e";
    $project = "my_projects";
    $url = $server."/".$project."/rest";
    $data['login_ticket'] = $login_ticket;


    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_FAILONERROR, true);

    $result = curl_exec($ch);
    if (curl_error($ch)) {
        throw new Exception(curl_error($ch));
    }
    $result = json_decode( $result );
    return $result;
}

With this function, we can access the api simply with a single line.  We can start with a simple ping.

$data = [
    'method' => 'ping'
];
echo executeREST($data);

This should print "OK", which means that the code has contacted the TACTIC server and was authenticated.  The method

Next, we can try a simple sobject with a search key:

$data = [
    'method' => 'get_by_search_key',
    'search_key' => $search_key,
];
print executeREST($data);

And we can also use expressions:

$data = [
    'method' => 'eval',
    'kwargs' => json_encode( [
        'expression' => '@SOBJECT(workflow/asset)',
        'single' => true,
    ] ),
];
$result = executeREST($data);

Note the difference in the arguments between this method (eval) and the last (get_by_search_key).  There are two ways for arguments to be passed through and both are valid for either function.  You can use the arguments explicitly or you can wrap the arguments in a kwargs key.  However, the kwargs key is assumed to be JSON encoded and allows for complex data structures to be passed through.  The post interface does not allow for complex data structures, so these should be JSON encoded.

This opens up the TACTIC API to many languages, in particular PHP and Ruby which are used in server side processing of popular web platforms.  All of these platforms have a very weak ability to handle complex data and really have no asset management capabilities.  This API makes it easy to integrate a powerful back-end with these content delivery systems.