Nerrvana API
You can interact with Nerrvana using the REST API.
Basics
Nerrvana's REST API call is a standard HTTP request to a defined URL in https://api.nerrvana.com domain. Each type of call has its own set of parameters which can be passed to it. API responds with data in XML format.
Authorization
Each request must contain an API public key and digital signature. An API public key is generated when you create a Nerrvana account and cannot be changed later. API private keys are used for request's digital signature generation and can be changed by you, if necessary. Both keys can be found on your Nerrvana account settings page.

To create a digital signature you will need to follow these steps:
  1. Define an array with request parameters, where keys are parameter names and values – data you are going to send.
  2. Sort an array by keys in ascending order
  3. Create a string from the resulting array with values following keys. If, for example, the first parameter 'name'  has value 'My project', the second parameter has name 'space_id'  with value 712 - the resulting string will be 'nameMy projectspace_id712'.
  4. Generate a digital signature with SHA256, using your API’s private key as a hash.
  5. Encode result with base64.
  6. Get MD5 hash from it.

PHP code sample:
<?php
$params = array();
$params['id'] = 712;
//API public key
$params['apikey'] = '036b9dae-0927-d2b4-99cc-d0886a5d2165';

ksort($params);
$signature = '';
foreach($params as $key=>$value){
    $signature .= $key . $value;
}
//API private key
$secretKey = "z3rCWlLdYAmQZ2kPw9X0LByc47Sco3XGhYsRJE3h7bL2o58LJA71oYAFduztU9xy8mGg7t";

// Computes the signature by hashing the salt with the secret key as the key
$signature = hash_hmac('sha256', $signature, $secretKey, true);
$signature = md5(base64_encode($signature));
?>
Sending data
At the moment we have implemented only basic functionality, but in the future we plan to support all four REST commands - GET, PUT, POST, DELETE.

CommandActionDescription
POST Create Creates an item (such as a test run)
GET Retrieve (Read) Retrieves an item or list of items (such as a list of executions)
PUT Update Modifies an existing item or list of items (such as changing the test run schedule)
DELETE Delete Permanently removes an item or group of items (such as deleting a test run)
Response
Nerrvana API returns a HTTP response containing code reflecting status of a request.

Response codeDescription
200 OK The request was processed successfully.
400 Bad Request The request cannot be fulfilled due to bad syntax.
401 Unauthorized Similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided.

If there was an error, the XML response will contain error messages, otherwise – data.
XML with error messages always has this format:
                <?xml version="1.0" encoding="utf-8"?>
                <errors>
                    <error>
                        <description><![CDATA['Space_id' parameter missing]]></description>
                    </error>
                    <error>
                        <description><![CDATA[Test run title missing]]></description>
                    </error>
                    ...
                </errors>
                
1
Interacting with Nerrvana Space.
A. Getting Space information

Request type - GET, URL - https://api.nerrvana.com/space/.

Parameters:

id - Space ID, integer

name - Space name, string. PostgreSQL LIKE syntax is allowed:

'abc' LIKE 'abc' true
'abc' LIKE 'a%' true
'abc' LIKE '_b_' true
'abc' LIKE 'c' false

Both parameters are optional. If both are missing, data about all Spaces will be returned.

Response – ‘HTTP 200 OK’ with the following XML payload:
                <spaces>
                    <space>
                        <id>12</id>
                        <name><![CDATA[Answers]]></name>
                        <ftp_path>Answers/_files/</ftp_path>
                    </space>
                </spaces>
                
If no data is found, an empty XML will be returned, as shown below:
                <spaces>
                    <no_space></no_space>
                </spaces>
                


API calls to create, rename and delete a Space are not implemented in this version.
B. Edit Space (not implemented)
C. Create Space (not implemented)
D. Delete Space (not implemented)
2
Interacting with Nerrvana Test Run.
A. Create a Test Run

Request type - POST, URL - https://api.nerrvana.com/testrun/.

Parameters you include into this request are matching with 'Add New Test Run' in UI's form. You can read more about them here.

Required parameters:

space_id - Space ID, integer

name - Test Run name, string

name - Test Run name, string

platforms - comma separated list of platforms, string. List of supported platforms can be also requested via API (see below).

executable_file – string, a path to an executable file relative to your FTP account home directory.


Optional parameters:

description – string, Test Run description.

validation - integer, with valid values 1 or 0. If 1, Nerrvana will validate Test Run before launching it. More details about validation in Nerrvana's documentation

start_date – date in DD/MM/YYYY format, date to start scheduled Test Run executions.

start_time – time in HH:MM format, time to start scheduled Test Run executions.

week_days – comma separated week days list, string. Defines week days to start test run on. Valid values are: 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'.

periodicity – integer. Test Run launch periodicity. If periodicity is 5 hours or 5 min – set this value to 5 and use period_type to define minutes or hours.

period_type – string. Periodicity units of measurement. Valid values: 'min', 'hrs'

nodes_count – integer. The number of Selenium Grid nodes, allocated to a single platform and used for parallel test runs. More information about the parallelization can be found here.

notify_email – string. An email you want to send an error report to. To use this option, the tests must use Nerrvana messages. More details about messages can be read here

If the request fails an error code and the XML message(s) will be returned. Otherwise, response will have HTTP 200 code and the XML containing Test Run object:
<?xml version="1.0" encoding="utf-8"?>
<testruns>
    <testrun>
        <id>1520</id>
        <space_id>712</space_id>
        <name><![CDATA[Test api test run creation]]></name>
        <description><![CDATA[]]></description>
        <executable_file><![CDATA[rebuildAndRun.sh]]></executable_file>
        <start_date>1371571566</start_date>
        <week_days></week_days>
        <start_time>16:06</start_time>
        <period_type></period_type>
        <periodicity></periodicity>
        <on_pause>0</on_pause>
        <validation>0</validation>
        <ftp_name>Test_api_test_run_creation</ftp_name>
        <platforms>
            <platform>
                <code>winxp_sp3_firefox_36</code>
                <name><![CDATA[Firefox 3.6/WinXP SP3]]></name>
            </platform>
            <platform>
                <code>win7_sp1_chrome_2301271</code>
                <name><![CDATA[Chrome 23.0.1271/Win7 SP1]]></name>
            </platform>
        </platforms>
        <nodes_count>1</nodes_count>
        <next_executions>
            <next_execution>
                <id>362923</id>
                <start_datetime>1371571566</start_datetime>
            </next_execution>
        </next_executions>
    </testrun>
</testruns>
                
B. Edit Test Run (not implemented)
C. Getting Test Run information (not implemented)
D. Delete (not implemented)
E. Get Test Run execution status

Request type - GET, URL - https://api.nerrvana.com/testrun/execution.

Parameters:

id - integer. Execution unique ID which will be returned during Test Run creation - next_executions –> next_execution -> id. From our example above a value of - 362923.

Response from Nerrvana server:
<?xml version="1.0" encoding="utf-8"?>
<executions>
    <execution>
        <id>362923</id>
        <testrun_id>1520</testrun_id>
        <start_datetime>1371496438</start_datetime>
        <status><![CDATA[completed]]></status>
        <platforms>
            <platform>
                <id>12128</id>
                <code>winxp_sp3_firefox_36</code>
                <name><![CDATA[Firefox 3.6/WinXP SP3]]></name>
                <browse_url>https://demo1001.ftp.nerrvana.com/test_space/_test_runs/Test_api_test_run_creation/2013_06_17_19_13_58/winxp_sp3_firefox_36/</browse_url>
                <status><![CDATA[completed]]></status>
                <messages>
                    <debug>
                        <message>
                            <txt><![CDATA[Search submitted]]></txt>
                            <created_time>1371500130</created_time>
                        </message>
                    </debug>
                    <info>
                        <message>
                            <txt><![CDATA[Test passed - text is present on the page.]]></txt>
                            <created_time>1371500140</created_time>
                        </message>
                    </info>
                </messages>
            </platform>
            <platform>
            ....
            </platform>
        </platforms>
    </execution>
</executions>
                
3
Getting a list of supported platforms.

Request type - GET, URL - https://api.nerrvana.com/testrun/platform.

No parameters

Response contains a list of supported platforms:
<?xml version="1.0" encoding="utf-8"?>
<platforms>
    <platform>
        <code>centos_58_firefox_36</code>
        <name><![CDATA[Firefox 3.6/CentOS 5.8]]></name>
    </platform>
    <platform>
        <code>win7_sp1_chrome_2301271</code>
        <name><![CDATA[Chrome 23.0.1271/Win7 SP1]]></name>
    </platform>
    ....
</platforms>
                
PHP code example – getting Space data by name and ID.
<?php
$params = array();
$params['id'] = 4023;
$params['name'] = 'space for test api';
$params['apikey'] = '036c9dae-0927-d2b3-91cc-d0286a5d2145';

ksort($params);
$signature = '';
foreach($params as $key=>$value){
    $request[] = sprintf('%s=%s', $key, urlencode($value));
    $signature .= $key . $value;
}

$secretKey = "ODA31TE5YzMtYWFjNS0xNjc0LWQ1NWUtKmJmNmY3MjE2NDg1MGJkNRQ2MTItNThhZS00MzI0LTgxMj5tNGU1Y2ZhOTFhZWU";

// Computes the signature by hashing the salt with the secret key as the key
$signature = hash_hmac('sha256', $signature, $secretKey, true);
$params['signature'] = md5(base64_encode($signature));

$request_body = http_build_query($params, '', '&');

$curl_options = array(
   CURLOPT_URL => 'https://api.nerrvana.com/space?'.$request_body,
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_SSL_VERIFYPEER => true,
   CURLOPT_SSL_VERIFYHOST => true,
   CURLOPT_CONNECTTIMEOUT => 2,
   CURLOPT_FORBID_REUSE => true,
   CURLOPT_FRESH_CONNECT => true,
   CURLOPT_HTTPHEADER => array()
);

$curl_handle = curl_init();
curl_setopt_array($curl_handle, $curl_options);

$response = curl_exec($curl_handle);

$http_status = curl_getinfo($curl_handle, CURLINFO_HTTP_CODE);
if ($http_status != 200) {
   /* some actions for errors */
    echo $response;
} else {
   //removing any output prior to proper XML response (ex. Nerrvana notices)
   $xml_start_pos = stripos($response, "<?xml");
   if ($xml_start_pos === false) {
       echo 'Incorrect response, expected but not received XML';
   }
   if ($xml_start_pos > 0) {
      $response = substr($response, $xml_start_pos);
   }
   echo $response;
}
?>
                
The API described here was created by us to implement our Nerrvana Jenkins plug-in. Missing bits and pieces can be implemented in a day's time upon request.