API Samples Overview

INTRODUCTION

The Issuetrak API 11.0 is a RESTful API that uses the HTTP protocol as the primary transport infrastructure both to invoke and API operation and to transmit the response from an API operation back to the API consumer. As such, the API is platform-agnostic.

Any API consumer platform that can transmit the appropriately defined payload via a valid HTTP application protocol request using the API HMAC authorization scheme (see the API Authorization Overview article for details about the authorization scheme) can communicate with the API.

Issuetrak has created two sample applications to demonstrate how to communicate with the API using two different application platforms: Microsoft .NET and PHP. The samples can be accessed here and are also available in the latest Issuetrak distribution, which can be downloaded from the following Knowledge Base Article (the article is password protected and can only be accessed by existing Issuetrak customers).

.NET SAMPLE

The .NET API sample relies upon an Issuetrak.API.Client library distributed with the sample as a .NET assembly. This Issuetrak.API.Client includes a set of wrapper methods to encapsulate the details of the process of calling the Issuetrak API for a particular operation.

For example, to retrieve a Note for a specific Note ID value, the Issuetrak.API.Client library exposes the following method signature:

Task<IssuetrakAPIResponse<ReadNoteDTO>> GetNoteForNoteIDAsync(GetNoteForNoteIDRequest request)

This signature indicates that the wrapper method is an asynchronous method that will return a Task with a task result of type <IssuetrakAPIResponse<ReadNoteDTO>>. The IssuetrakAPIResponse class provides a wrapper to encapsulate the details of an API response with properties such as “ResponseStatusCode” to retrieve the HTTP status code of the HTTP response and “ResponseText” to provide the raw string response of the HTTP response.

To call the GetNoteForNoteIDAsync API method , the Issuetrak.API.Client library may be invoked as in the following C# example:

using (IssuetrakAPIClient client = new IssuetrakAPIClient(API_KEY)) 
{ 
  GetNoteForNoteIDRequest request = 
     new GetNoteForNoteIDRequest(BASE_API_URL, API_VERSION, noteID);
  IssuetrakAPIResponse response = await client.GetNoteForNoteIDAsync(request);
}

In the sample, the “API_KEY” constant is the API key text value that is used for the API authorization scheme. The “BASE_API_URL” constant is the root URL to the Issuetrak API instance, and the API_VERSION constant is the integer identifier for the desired API version, e.g., 1.

The “noteID” parameter is a variable that is used to identify the desired Note ID value to retrieve.

PHP Sample

The PHP sample project demonstrates how to interact with the Issuetrak API 10.3 via standard PHP functions to include code samples to:

  1. Create a New Note
  2. Retrieve a Note by Note ID
  3. Retrieve Issues by Issue Number List

The PHP sample also demonstrates how to employ standard PHP functions to generate the authorization headers for API authorization.

The PHP sample is included in the “index.php” file reproduced in full below. To execute the PHP sample, copy the text for the “index.php” file to an appropriately configured PHP web server and update the “$base_url” and “$api_key” PHP variables with the appropriate values for the Issuetrak API deployment.

<?php
$base_url = "http://mysite.example.com";
$api_key = "API KEY GOES HERE";
$hash_algorithm = "sha512";


testGetRequest();
testPostRequest();


function testGetRequest()
{
	$request_method = "GET";
	$request_path = "/api/v1/notes/1";
	$request_query = "";
	$request_body = "";

	$response = ExecuteApiCall($request_method, $request_path, $request_query, $request_body);

	echo "RESPONSE = " . $response . "\n";
}

function testPostRequest()
{
	$request_method = "POST";
	$request_path = "/api/v1/notes";
	$request_query = "";
	$request_body = <<<END
{
	"IssueNumber": 1,
	"CreatedDate": "2018-01-01T12:32:32-04:00",
	"CreatedBy": "APIUser",
	"ShouldSuppressEmailForCreateOperation": false,
	"NoteText": "Testing note creation from PHP.",
	"IsPrivate": false,
	"IsRichText": false
}
END;

	$response = ExecuteApiCall($request_method, $request_path, $request_query, $request_body);

	echo "RESPONSE = " . $response . "\n";
}

function ExecuteApiCall($method, $requestPath, $requestQuery, $requestBody)
{
	date_default_timezone_set("UTC");
	$request_time_iso8601 = gmdate("Y-m-d\TH:i:s") . substr((string)microtime(), 1, 8) . "Z";
	$request_guid = guid();

	$request_summary = implode("\n", [$method, strtolower($request_guid), $request_time_iso8601, strtolower($requestPath), 	$requestQuery, $requestBody]);
	$request_signature = base64_encode(hash_hmac($GLOBALS['hash_algorithm'], $request_summary, $GLOBALS['api_key'], true));

	$http_headers = array(
		"Content-Type: application/json",
		"X-Issuetrak-API-Timestamp: " . $request_time_iso8601,
		"X-Issuetrak-API-Request-ID: " . $request_guid,
		"X-Issuetrak-API-Authorization: " . $request_signature
	);


	$curl = curl_init();
	curl_setopt($curl, CURLOPT_URL, $GLOBALS['base_url'] . $requestPath . $requestQuery);
	curl_setopt($curl, CURLOPT_HTTPHEADER, $http_headers);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

	if($method === 'POST')
	{
		curl_setopt($curl, CURLOPT_POST, 1);
		curl_setopt($curl, CURLOPT_POSTFIELDS, $requestBody);
	}

	$response = curl_exec($curl);
	curl_close($curl);

	return $response;
}

function guid()
{
	if (function_exists('com_create_guid'))
	{ # this happens on Windows
		return com_create_guid();
	}
	else
	{ # this happens on other platforms

		$charid = md5(uniqid(rand(), true));
		$hyphen = chr(45); # "-"
		$uuid = substr($charid, 0, 8) . $hyphen
			. substr($charid, 8, 4) . $hyphen
			. substr($charid,12, 4) . $hyphen
			. substr($charid,16, 4) . $hyphen
			. substr($charid,20,12);

	return $uuid;
	}
}

?>