Basic Operations#

For most ICE ClusterWare™ objects, standard HTTP actions are supported for manipulating the entries. Using the Node objects as an example:

  • List objects - GET /nodes

  • Create new object - POST /nodes

  • Get object info - GET /node/<UID>

  • Update some info - PATCH /node/<UID>

  • Update all info - PUT /node/<UID>

  • Delete object - DELETE /node/<UID>

  • Metadata - GET /nodes/meta

Endpoints that refer to a whole class of objects are pluralized (end with ‘s’), such as /nodes or /images. Endpoints that refer to one specific object are singular and include a UID, such as /node/<UID> or /image/<UID>.

List Objects#

Issuing an HTTP GET to an object-class (pluralized) endpoint will return information about all the objects of that class. Since this endpoint will only return a list of UIDs for the objects, any detailed information will have to be found with a subsequent call to the GET endpoint.

The return value will be a JSON object with two main fields: success and data. The data field will also be a JSON object, with the keys being set to object UIDs:

{ “success":  true, "data":  { "7ad57…73e4a1f4": {… first object’s data …}, \
    "ab89c…2501817": {… second object’s data …}}}

If the request is unsuccessful, then a reason field will be returned with more information on why the request failed.

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

Create New Object#

To create a new object, a POST is issued to the object-class (pluralized) endpoint with the relevant data. Most object types accept a name and "description" field, but most fields are object-specific (see below for details).

To create a new compute-node object:

curl -X POST https://head1.cluster.local/api/v1/nodes --data \
    '{"mac":"11:22:33:44:55:66"}' -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

On success, the ClusterWare platform will return a UID for the newly create node:

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

Upon failure, the returned data will include a "reason" field with more information on why the request failed:

{ “success": false, "reason": "Node with MAC=52:54:00:00:00:03 already exists." }

Get Object Info#

Issuing an HTTP GET to an endpoint will return information about a specific object. Depending on the object type, the UID may be the true UID for the object, the name of the object, or some other object-specific unique identifier such as MAC address (for nodes).

The return value will be a JSON object with two main fields, success and data. The data field will also be a JSON object with a single key-value pair. The key will usually be the object’s UID, but if the request was made with the object’s name, then the key will also be the name.

{ "success":  true, "data":  { "7ad57…73e4a1f4": { … object data … }}}

By default, GET operations will return all of the object’s information: the UID, the name, and all object-specific fields and sub-fields. The client is expected to provide any filtering of data that might be needed.

If the request is unsuccessful, then a reason field will be returned with more information on why the request failed.

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

Update Object#

There are two related update methods: PATCH and PUT. When using the PATCH method, the request is assumed to modify only those fields that are sent in the request – any other fields in the object will be left as-is. The PUT method assumes that the entire object should be overwritten by the new data – any fields in the request will be overwritten, and any fields not in the request will be removed or set to default values. Not all object-types allow for PUT operations, and note that a bad PUT call could irreversibly damage the object if some fields are wiped out.

To update the "description" field of a node with PATCH:

curl -X PATCH https://head1.cluster.local/api/v1/node/UID --data \
    '{"description":"this is a new description"}' -H "Authorization: Bearer \
    eyJhbGciOiJIUzI1Ni…"

The return value will simply indicate success or failure:

{"success": true}

In this example, success would indicate that ONLY the "description" field has been modified.

On failure, a "reason" field will give more information on why the request failed:

{"success": false, "reason": "Unhandled parameter(s): ..."}

Delete Object#

The DELETE method will permanently remove an object from the ClusterWare system – there is no way to recover the object’s data once it has been deleted.

To delete an Image from the system:

curl -X DELETE https://head1.cluster.local/api/v1/image/DefaultImage -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

The return value will simply indicate success or failure:

{"success": true}

On failure, a “reason” field will give more information on why the request failed:

{"success": false, "reason": "No image found for ID=DefaultImage"}

Metadata Information#

All objects have a metadata endpoint off of their object-class (pluralized) endpoint (for example, /nodes/meta). This endpoint will return more detailed information about the fields available in that object-class.

Note that this is a public endpoint and does not need any authentication token to be accessed.

curl -X GET https://head1.cluster.local/api/v1/nodes/meta

It will return a JSON object that includes a list of fields. Each field in the list will include a path field (the chain of keys to get to that field), summary, source (where the data comes from), and a format (what kind of data it is).