Server Automation REST API

This page has not been liked. Updated 10/23/13 10:43 AM by DaraMurphyTags: None

Interacting with Server Automation via the REST API

 

You can execute and monitor Automation Plans through the REST API.

Using the REST API allows you to to perform these tasks in a standardized and operating system independent method.

NOTE: ALL REST REQUESTS REQUIRE THE USE OF THE HTTPS PROTOCOL:



The REST API implements SSL (HTTPS) using a self-signed certificate, so the first time a client attempts to connect to it, they may be required to first accept / trust the certificate. This is especially true if the client is a web browser (or browser plugin, such as Firefox's Poster). The confirmation request would only occur the very first time a connection attempt is made. The same would be true of the demo application.

 

 

Deployment environment

The Server Automation REST API is installed/uninstalled by means of two tasks that can be found on the "Server Automation" site, namely:

- (ID: 108) Deploy IBM Endpoint Manager for Server Automation REST API

- (ID: 109) Remove IBM Endpoint Manager for Server Automation REST API

The REST API itself is a java-based web application deployed within a WebSphere Application Server with Liberty Profile.

The starting / stopping of this server is controlled by means of a Windows service called "WASLibertyService":



This service is automatically started after installation, but may require manual starting upon host machine restart.

The server logs can be found at:

<INSTALL ROOT>\wlp\usr\servers\defaultServer\logs

 

 

How it works

Using the REST API, you submit the ID of an existing plan (fixlet) via the URL (a GET operation). This retrieves a simplified XML structure representing all of the data required to run that plan. The client must then complete this XML and return it to the REST API to execute the automation plan (a POST operation).

 

Between the time the XML is received from REST and sent back for execution, clients can modify this XML to:

  • Schedule a plan action

  • Specify a custom name for new plan actions created via REST

  • Enable/Disable prefetching

 

When executing the plan, the client must specify the following for each plan step before execution:

  • any required parameters for a plan step

  • any required parameters for the corresponding failure step (if a failure step been defined)

  • one or more target computers (by name and/or ID) or one or more target groups (by name)

 

The REST API response to on successful execution of an automation plan is the ID of the new plan action.

If the Client supplies Invalid XML, the REST API will return a HTTP Error 400 "Bad request"

If the Client supplies the ID of a Plan that does not exist, the REST API will return a HTTP Error 404 "Not Found"

If an internal or unexpected error occurs, the REST API will return a HTTP Error 500 "Internal Server Error"

The API is not responsible for authentication of the client login details. The underlying IBM Endpoint Manager API authenticates when it is first invoked.

The Server Automation REST API uses the HTTPS protocol (as does the demo application).

 

 

Demonstration application

Server Automation provides a demo application that shows how you can use the REST API to complete the following functions:

  • Run an Automation Plan

  • Schedule an automation plan action

  • Specify a custom name for a plan action before creating it.

  • Enable prefetching

  • Stop an Automation Plan

  • Create a new Automation Plan

  • Monitor a running Automation Plan

 

 

Functionality

You can use the REST API to complete the following:

  • Run an Automation Plan

  • Schedule an automation plan action

  • Change the name of an existing automation plan action

  • Enable prefetching

  • Stop an Automation Plan

  • Create a new Automation Plan

  • Monitor a running Automation Plan

  • Use a plan containing fixlets requiring parameter encryption

  • Use a plan containing fixlets containing advanced parameters

 

 

General URL format

Requests must conform to this basic format:

/serverautomation/{resource}/{site type}/{site name}/{object id}

{resource}

The desired resource - plan, planaction, ...

{site type}:

The type of site:

    • external

    • operator

    • custom

    • master

{site name}:

  • The name of the site, for example, Server Automation.

  • This is not required for the master action site.

  • Operator name is the site name for operator sites.

{object id}:

  • The ID of the objects that you are requesting, this varies per context but is generally the integer value ID of an object in the database.

  • If the OBJECT_ID is not supplied, the request might display a description of objects in this site of this resource.

 



Resources