Getting started
Installing, configuring, and checking the API module
For information on installing and configuring, refer to
To make sure that the API is up and running, you can quickly check it using a web browser. For more information, see
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/
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 |
---|---|
|
The MIME type of the body of the POST request is JSON.
|
|
Content-Types that are acceptable for the response. For XML:
For JSON (default setting):
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. |
|
Credentials for HTTP authorization.
Example:
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. |