KSplice Uptrack PHP REST Client

Ever get tired of rebooting your linux server after a kernel update? KSplice has created a tool that allows for kernel updates to occur without having to reboot your server. They provide a web interface at ksplice.com to manage your servers through their GUI, but I had the need to create a PHP client to interact with the KSplice API. Unfortunately the developer documentation is very lack luster, so I am going to give you some help.

I chose to use the Zend framework because it has the Zend_Rest_Client available to build upon. There are really only three different API calls on the KSplice Uptrack REST web service: machines, describe, and authorize.

machines:
returns a JSON list of all the servers registered with KSplice Uptrack
POST /api/1/machines

describe:
returns a JSON of a specific server
POST /api/1/machine/$UUID/describe

authorize:
enables or disables a specific server from using KSplice Uptrack
POST /api/1/machine/$UUID/authorize

First off I create my class and two variables that will be used. One for the Zend_Rest_Client, and the second for the base URI.

/** 
* RestClient for the KSplice Uptrack API 
* 
*/

class Ksplice_Uptrack_RestClient
{

    protected $restClient;
    private   $baseUri;

    public function __construct()
    {
        $baseUri = "https://uptrack.ksplice.com/api/1";
    }

The next piece of the puzzle is creating generic POST and GET functions to be used by the actual API calls. These will return PHP Std_Objects after decoding the JSON returned by the KSplice Uptrack API.

    private function restPost()
    {
        $response = $this->restClient->getHttpClient()->request('POST');
        $this->errorHandler($response);

        return Zend_Json::decode($response->getBody(), Zend_Json::TYPE_OBJECT);
    }

    private function restGet()
    {
        $response = $this->restClient->getHttpClient()->request('GET');
        $this->errorHandler($response);

        return Zend_Json::decode($response->getBody(), Zend_Json::TYPE_OBJECT);
    }

I have added an brief error handler.

    private function errorHandler($response)
    {
        if (!($response instanceof Zend_Http_Response) && !($response instanceof Zend_Rest_Client_Result)) {
            throw new Exception("Invalid KSplice response received.");
        }

        switch (get_class($response)) {
            case 'Zend_Rest_Client_Result':

                break;

            case 'Zend_Http_Response':
                $restJsonAsObject = Zend_Json::decode($response->getBody(), Zend_Json::TYPE_OBJECT);
                if ($response->isError()) {
                    $responseCode = intval($response->getStatus());
                    throw new Exception("KSplice Error Received: {$restJsonAsObject->error}");
                }

                break;

            default :
                throw new Exception("Cannot process KSplice request at this time.");
                break;
        }
    }

KSplice Uptrack's REST API requires custom headers for authentication and the API calls are appended to the base URI we defined in the constructor. I will add generic methods to set both the request headers and the URI. Additionally, the authorize API call requires raw data in the form of JSON to be sent, so I will add a method to set the raw data of the request.

    private function setUri($uri)
    {
        $this->restClient->getHttpClient()->setUri($uri);
    }

    private function setHeaders($header, $value)
    {
        $this->restClient->getHttpClient()->setHeaders($header, $value);
    }

    private function setRawData($data, $contentType = "application/json")
    {
        $this->restClient->getHttpClient()->resetParameters();
        $this->restClient->getHttpClient()->setRawData($data, $contentType);
    }

Now for the final three methods: getMachines, getServer, authorizeServer

getServer and authorizeServer require the UUID to build the URI to the KSplice Uptrack REST service. This is the UUID that was created during the installation of Uptrack on your server. I store it in a database, but it is also found at

    public function getMachines()
    {
        $this->restClient = new Zend_Rest_Client($this->configuration->host);
        $this->setUri($this->baseUri.'/machines');
        $this->setHeaders('X-Uptrack-User', "MyKspliceUser);
        $this->setHeaders('X-Uptrack-Key', "MyKspliceUptrackKey");
        return $this->restGet();
    }

    public function getServer($uuid)
    {
        $this->restClient = new Zend_Rest_Client($this->configuration->host);
        $this->setUri($this->baseUri.'/machine/'.$uuid.'/describe');
        $this->setHeaders('X-Uptrack-User', "MyKspliceUser);
        $this->setHeaders('X-Uptrack-Key', "MyKspliceUptrackKey");
        return $this->restGet();
    }


    public function authorizeServer($uuid, $authorized = "true")
    {
        $data = '{"authorized": '.$authorized.'}';
        $this->restClient = new Zend_Rest_Client($this->configuration->host);
        $this->setUri($this->baseUri.'/machine/'.$uuid.'/authorize');
        $this->setHeaders('X-Uptrack-User', "MyKspliceUser);
        $this->setHeaders('X-Uptrack-Key', "MyKspliceUptrackKey");
        $this->setRawData($data);
        return $this->restPost();
    }

}