The OpenCenter CLI implements the OpenCenter API through the command line interface. This chapter discusses the OpenCenter API for users that want to interact directly with the API.

Overview

The OpenCenter API is a RESTful API with two base URIs, a user endpoint and an admin endpoint.

About the User Endpoint

Calls sent to the user endpoint do not immediately commit changes to the database; instead, the OpenCenter solver determines the most efficient way to execute the request before committing the change. The user endpoint is located at the root of the OpenCenter server. For example, if your OpenCenter server's IP address was 192.0.2.1:8443, you would access the user endpoint at https://192.0.2.1:8443/api_uri.

For example, when you use the UI to move a node from the Unprovisioned container to a Nova infrastructure container, the OpenCenter solver determines the operations that need to be performed on the node to turn it into a Nova Controller node; among other things, the system needs to install Chef client on the node, set the node in Chef to be a Nova infrastructure node, reset the parent_id fact, and more.

About the Admin Endpoint

Calls sent to the admin endpoint are directly recorded in the database, and should be used with caution. The admin endpoint is located at /admin. In the above example, admin API calls go to https://192.0.2.1:8443/admin/api_uri.

In this case, if you were to use the admin API to simply change a node's parent_id from the Unprovisioned container to the Nova infrastructure container, the parent_id information would be changed in the OpenCenter database, but no actual work would be performed, and the node would not be correctly provisioned with a Chef client or any Nova infrastructure information.

Authentication

The OpenCenter API currently uses basic authentication and should be run over https://. Use the username and password for the server node.

Notifications and Errors

The OpenCenter API returns standard HTTP response codes. Admin API calls always return a 200 or a 404 immediately. User API calls on facts or adventures may indicate that the request is still being processed or requires more information.

For example, the following API call attempts to run an adventure on a node, but the adventure requires arguments:

curl http://localhost:8443/adventures/6/execute -d '{"node": 4}' -H "content-type: application/json"

The system response on the call will be as follows:

{
  "status": 409,
  "message": "need additional input",
  "plan": [
    {
      "args": {
        "sleep_interval": {
          "message": "I cannot solve for type \"int\"",
          "required": true,
          "type": "int"
        }
      },
      "primitive": "sleep",
      "ns": {},
      "timeout": 30
    }
  ],
  "friendly": "Please supply additional info"
}

API Operations

This section documents the API operations and parameters available in the OpenCenter API.

Nodes

A node is any object that can be managed within the environment. It may be a container (such as a Nova cluster) or a server (such as a Chef server). If you are using Cloud Files, your environment will contain a Cloud Files node that includes authorization keys and any other attributes relevant to your Cloud Files account.

In the following example, a node is assigned the name test and the ID number 15.

echo '{"name":"test","id":15}' | curl -d @- -H 'Content-Type: application/json' -X PUT http://192.0.2.1:8443/nodes/15

Facts

A fact is a property that can be inherited from a parent node. For example, if a node is placed within a Nova container, the node inherits the container's properties. These properties can include the Chef server that the container uses, the API server, and the nova configuration file information. Each node includes a fact that describes its parent, which determines what additional facts the node needs to inherit.

In the following example, a fact called fact73 is created and assigned to node 5. The value of the fact is not specified in this example, but could be a JSON string.

echo '{"key": "fact73", "node_id" :5}' | curl -d @- -H 'Content-Type:application/json' -X POST http://192.0.2.1:8443/facts/

Attributes

Attributes are properties that are specific to a single node and are not inherited. These attributes are distinct and unique to the node, such as RAM or disk space.

In the following example, an attribute called called attr5 is created and assigned to node 8.

echo '{"key": "attr5", "node_id": 8, "id": "1234"}' | curl -v -d @- -H 'Content-Type: application/json' -X POST http://192.0.2.1:8443/attr/

Primitives

A primitive acts on a node and manipulates the node facts. Primitives are extensible via Python.

Tasks

A task is an action directed at a specific node, assigned by the OpenCenter server to the OpenCenter agent that is installed on the node. A task may use one or more primitives to accomplish the action. Tasks are extensible via Python.

In the following example, task 3 performed on node 15.

echo '{"id":"3","node_id":15}' | curl -d @- -H 'Content-Type: application/json' -X PUT http://192.0.2.1/tasks/3

Adventures

An adventure is a solution composed of multiple actions that run in sequence, created to manage common changes. For example, OpenCenter includes an adventure that installs Chef server. There are also adventures for rebooting a server, upgrading installation packages, and identifying out-of-date security patches.

In the following example, adventure 8 is executed on node 6.

echo '{"node":6}' |curl -d @- -v -H 'Content-Type: application/json' http://192.0.2.1/adventures/8/execute

Filters

Filters are used to organize nodes by type.

Filters of the interface type select objects that offer a service. For example, a chef-server interface is a filter expression that shows what kinds of facts a Chef server has:

id: 1 
name: chef-server 
type: interface 
expr: (facts.chef_server_uri != None) and (facts.chef_server_pem != None)

A node that has the facts defined in the expression field is a Chef server. In future releases, additional interfaces will be defined to allow more detailed sorting of nodes within an OpenCenter environment.