API Reference#

The ICE ClusterWare™ Application Programming Interface (API) enables cluster management, monitoring, and provisioning using a series of HTTP requests. While this web API is typically accessed by using the provided web portal and command line tools, users can also create their own customized tools by calling the web API in their own scripts.

Aside from a couple of endpoints related to long-running background jobs, the ClusterWare API is stateless, meaning there is no need for the client to remember any previous state information.

The API is organized around the major ClusterWare objects:

  • Nodes - /nodes

  • Attribute Groups - /attribs

  • Admins - /admins

  • Login/Authentication endpoints

  • Boot Configurations - /bootconfigs

  • Images - /images

  • Networks - /nets

  • Hostnames - /hosts

  • Dynamic Groups - /dyngroups

  • Naming Pools - /namingpools

  • Head nodes - /heads, /database

  • Software Repositories - /repos

  • Software Distributions - /distros

  • Git Repositories - /gitrepos

  • State Sets - /nodes/waitfor

  • Cluster-wide information - /cluster

Each ClusterWare object type has several method endpoints for getting or setting data that can be accessed using an HTTP call to the correct endpoint. For example, an HTTP GET call to the /nodes endpoint will return a list of all known nodes.

Some method endpoints also accept a unique identifier (UID) as part of the URL. For example, an HTTP GET call to /node/<UID> will return details about the node with the matching UID. A UID is a 32-character string of lower-case letters and digits, such as bf0f61d24ce84064a8c7c7e872332c07 or e54e420c42214101918584e27382e8f5.

Many method endpoints that accept a UID will also accept other identifiers in place of a UID. For example, calls to Admins endpoints can use a username in place of the UID and calls to the Nodes endpoints can accept a node name, MAC address, or IP address in place of the UID.

Data being sent to web API endpoints is expected to be encoded in JSON format. Usually this data will be an JSON object (hash-table or dictionary), though some endpoints accept a list or string instead.

The HTTP response from the server will usually be a JSON object. When an HTTP request is successful, the response will have an HTTP status code of 200, the JSON object will contain a "success" entry with a value of true, and any additional data can be found in the "data" entry. For example:

{ "success": true, "data": "4e75fa48…0f005bd" }

If the HTTP response fails, then a 400-series status code will be returned (e.g. 401 for invalid credentials; 403 for denied access; 404 for object not found, etc.), the "success" entry will have a value of false, and a "reason" entry will have a description of why the action failed. For example:

{ “success":  false, "reason": "No node found for ID=n123" }