AAI REST API

This section gives you an overview of the purpose, function, and implementation of the REST APIs for Automic Automation Intelligence.

Main AAI REST API

The AAI REST API allows you to communicate with your system using a technology-independent, state-of-the-art interface. The API reference is written in OpenAPI (Swagger) and all exchanges are in JSON format. For a complete list of available AAI REST API endpoints and their required parameters, go to the AAI REST API page:

http://<aai hostname>:8080/aai/devPreview/

Each endpoint has one or more operations available. You can use the following options:

• Show/Hide: Allows you to display or hide the list of operations available.

• List Operations: Lists the operations available for the respective endpoint.

• Expand Operations: Opens the details of all operations available for the respective endpoint.

Once you expand an operation you can see a brief description of its purpose as well as all relevant parameters. POST operations include examples of how to use them. You can also try out all the operations available.

REST API Specification

The following REST API calls are available:

• POST to create data
• GET to retrieve data
• PUT to update data
• DELETE to delete data

The API is generally limited to two (2) levels of nested resources to minimize overlap.

Example

You can get Jobs for a Scheduler by calling /schedulers/{schedulerId}/jobs, however to get the Runs for a Job, you call /jobs/{jobId}/runs.

Exception Handling

HTTP Status Codes are generally used to indicate processing results. Whenever practical and useful, details of the error condition are reported back to the caller as a JSON formatted object.

Common HTTP Status Codes and Usage in the REST API

• HTTP 200 - OK: The information you requested should be in the payload

• HTTP 201 - Created: The request has been fulfilled and resulted in a new resource being created.

• HTTP 202 - Accepted: The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.

• HTTP 204 - Empty Response: Everything is OK, however there are no results to return to the caller. Commonly used for "action" type calls to the API.

  Note: This is currently not in-use, due to a bug with IE 8 and IE9. Instead, responses will have an HTTP 200 status code, along with some type of payload in the response.

• HTTP 400 - Bad Request: When a call does not contain valid input or when an API is not yet implemented. See error detail payload for additional information {Error : unexpected JSON format}

• HTTP 401 - Unauthorized: When a call does not contain valid input or when an API is not yet implemented. See error detail payload for additional information

• HTTP 404 - Not Found: Returned when the requested resource is not found in AAI.

• HTTP 422 - Unprocessable Entity: When the call is well formed but the data was incorrect. {Error : Well-formed JSON, bad data}

• HTTP 500 - Internal Server Error: Something unexpected went wrong on the server side. See error detail payload for additional information

From the REST API page you can also access the API DOCS page, which offers lists of the different properties that can be used for REST API queries as well as some implementation examples.

Subscription Services REST API

A second REST API page allows you to subscribe to information published by Automic Automation Intelligence such as alerts, definitional data, events and predictions. You can then use these subscriptions to feed the information to other parts of your system. For more information, see REST API Specification for Subscription Services.

This section includes the following pages:

• REST API Specification for Subscription Services

• REST API Specification - Custom Job Scheduler Integration