API User's Guide

Getting started

Installing, configuring, and checking the API module

For information on installing and configuring, refer to Installation Guide: Installing and Configuring the API Module.

To make sure that the API is up and running, you can quickly check it using a web browser. For more information, see Installation Guide: Checking the API Module.

Default URL to access the API

It is further assumed that the API handler application is installed in a virtual directory named api. For example:

http://www.example.com/api/

TIP: To view the API URL, start the Web Configuration tool on the web server and navigate to the API module using the sidebar. The URL will be displayed in the main pane, among other configuration information.

HTTP request methods

Alloy Navigator Express API calls utilize two HTTP request methods: GET and POST.

URL uncoding

All URL elements and parameters must be URL-encoded.

INFO: For more information on URL encoding, see https://en.wikipedia.org/wiki/Query_string#URL_encoding.

Below is an example of a URL with encoded parameters.

Parameters:

Assignee=John Doe
par_sort_desc=Created_Date
par_fields=Ticket,Due_Date,Summary
par_offset=50
par_limit=20

URL with encoded parameters:

http://www.example.com/api/v2/Tickets?Assignee=John%20Doe&par_sort_desc=Created_Date&par_fields=Ticket%2CDue_Date%2CSummary&par_offset=50&par_limit=20

Date and time format

All dates and timestamps submitted through the API must follow the W3C DateTime format. For details, see Date and time format.

HTTP request headers

Alloy Navigator Express API calls utilize the following HTTP headers:

Header Description

Content-Type

The MIME type of the body of the POST request is JSON.

Content-Type: application/json

Accept

Content-Types that are acceptable for the response.

For XML:

Accept: text/xml or Accept: application/xml

For JSON (default setting):

Accept: json

NOTE: You can specify the XML response format for all API requests except when obtaining the API access token. The API access token is always returned in the JSON format.

Authorization

Credentials for HTTP authorization.

Authorization: bearer <token>

Example:

Authorization: bearer GW9x4uiH7SHq...4uiH7S

NOTE: You should specify this header only if the API is configured for Access Token authentication. For more details, see Authenticating users.

Response format

The default response format is JSON.

INFO: The API also supports the XML format. If you want to receive responses in the XML format, specify it in the request’s Accept header. For more details, see HTTP request headers.

Below you can see examples of JSON responses.

A response to a correct request:

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
	  //... 
}

A response to an incorrect request:

{
	"success": false,
	"errorCode": 101,
	"errorText": "<An error message>",
	"responseObject": null
}

Error messages

The following errors may appear:

Error message Description
Invalid request body.

The request body is invalid or missing.

For example, the POST request body contains invalid JSON data.

Authorization has been denied for this request.

The Authorization header is missing, or the token has expired.

You do not have enough permissions to access this item.

The user is not authorized to view the requested object.

This action cannot be executed because the action's condition is not satisfied.

The workflow Action cannot be performed because the object or the user does not satisfy the action's condition.

NOTE: The action's condition defines types and statuses the current object must have, roles the current user must be a member of, and may also include additional criteria.

Requested object is of unknown class.

The object class with the specified name was not found.

Object <OID> not found.

The record with the specified object identifier was not found.

Requested action is not available.

The workflow Action with the specified ActionID was not found.

Field <name> is unknown.

The field with the specified name was not found.