Working with the API (RaaS)

The API (RaaS) refers to the application server that SaltStack Config clients connect to. These clients include the user interface component of SaltStack Config, properly configured masters, and other users of RaaS. The application server is also known as the eAPI server.

RaaS is organized into modules (called “resources”) and functions (called “methods”). In the API call test.echo(‘hello, world’), the resource is test and the method is echo(). Arguments can be passed to methods by position or by keyword.

RaaS can be accessed in two ways: via an RPC client and via an HTTP (or HTTPS) bridge.

To connect to RaaS, set these options in client = APIClient():

server
username
password
config_name=’internal’ Change to authentication backend name if using LDAP
timeout=60 # Take at most 60 seconds to perform any operation
ssl_key=None
ssl_cert=None
ssl_context=None
ssl_validate_cert=True = Set to False if using self signed certs

Example:

from sseapiclient import APIClient
client = APIClient('https://localhost', 'root', 'PASSWORD', ssl_validate_cert=False)

Note:

In versions prior to 6.2, the API connection was made using SyncClient.connect(), which is still compatible with versions 6.2 and up. If you are using SyncClient.connect(), no changes are required.

API syntax

client.api.<interface>.<method>(parameter=parameter_value)

Example:

from sseapiclient import APIClient
client = APIClient('https://localhost', 'root', 'PASSWORD')
client.api.sec.download_content(auto_ingest=True)

Using the API (RaaS) with Curl

You can also use RaaS with directly with HTTP and JSON. The following is an example of using the API with curl. Note when xsrf is enabled you will need to obtain an xsrf cookie and token first. See HTTP Bridge on how to obtain and use an xsrf token and cookie. When using the Python API client, this is done automatically by default.

Example:

curl --user 'root:PASSWORD' --url 'https://localhost/rpc' \
  --data '{
    "resource": "sec",
    "method": "download_content",
    "kwarg": {"auto_ingest": true}
  }'

Licensing

The SaltStack Config user interface displays notifications to warn when your license is close to expiring. As a RaaS user, you must use the License workspace to track license status and ensure it stays active. If your license expires, the RaaS service stops.

RPC client

The programmatic RPC clients in the sseapiclient module work with Python version 2.7 and Python version 3.5 or later. The clients connect to SSE via HTTP or HTTPS and authenticate. Using the RPC client has the advantage of being somewhat easier to use than the HTTP bridge.

HTTP Bridge

The HTTP (or HTTPS) bridge accepts JSON payloads POSTed to an endpoint exposed by SSE, translates the payloads into RPC calls, then returns the result as JSON. The endpoint supports cookie-based authentication so that authentication credentials need to be passed only once per session. The bridge also allows sending multiple calls in a single payload.

If xsrf is enabled (default with state install) in the /etc/raas/raas.conf tornado_xsrf_cookies_enabled: True you will need to provide the X-Xsrftoken: on the header of the rest call. The best way is to save a cookie with a get call then use the cookie to provide the header token. This cookie is saved in the $HOME (users home) directory. The payload is a dictionary.

Example curl call with xsrf header:

curl -k -c $HOME/eAPICookie.txt -u root:PASSWORD 'https://localhost/account/login' >/dev/null
curl -k -u root:PASSWORD -b $HOME/eAPICookie.txt \
  -H 'X-Xsrftoken: '$(grep -w '_xsrf' $HOME/eAPICookie.txt | cut -f7)'' \
  -X POST https://localhost/rpc \
  -d '{
    "resource": "sec",
    "method": "download_content",
    "kwarg": {"auto_ingest": true}
  }'

The samples assume:

client=APIClient(<addr>,<user>, <pwd>)
Default state based install of eAPI
SSL enabled
Import of sseapiclient. Example:
```
from sseapiclient import APIClient
```