# rest_wsgi

## A minimalist REST API for Salt

This `rest_wsgi` module provides a no-frills REST interface for sending commands to the Salt master. There are no dependencies.

Extra care must be taken when deploying this module into production. Please read this documentation in entirety.

All authentication is done through Salt's external auth system.

## Usage

- All requests must be sent to the root URL (`/`).

- All requests must be sent as a POST request with JSON content in the request body.

- All responses are in JSON.

See also

`rest_cherrypy`

The `rest_cherrypy` module is more full-featured, production-ready, and has builtin security features.

## Deployment

The `rest_wsgi` netapi module is a standard Python WSGI app. It can be deployed one of two ways.

### Using a WSGI-compliant web server

This module may be run via any WSGI-compliant production server such as Apache with mod_wsgi or Nginx with FastCGI.

It is strongly recommended that this app be used with a server that supports HTTPS encryption since raw Salt authentication credentials must be sent with every request. Any apps that access Salt through this interface will need to manually manage authentication credentials (either username and password or a Salt token). Tread carefully.

### salt-api using a development-only server

If run directly via the salt-api daemon it uses the wsgiref.simple_server() that ships in the Python standard library. This is a single-threaded server that is intended for testing and development. This server does not use encryption; please note that raw Salt authentication credentials must be sent with every HTTP request.

Running this module via salt-api is not recommended!

In order to start this module via the `salt-api` daemon the following must be put into the Salt master config:

    rest_wsgi:
        port: 8001

## Usage examples

POST /

  Example request for a basic `test.ping`:

      % curl -sS -i \
              -H 'Content-Type: application/json' \
              -d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"local","tgt":"*","fun":"test.ping"}]' localhost:8001

  Example response:

      HTTP/1.0 200 OK
      Content-Length: 89
      Content-Type: application/json

      {"return": [{"ms--4": true, "ms--3": true, "ms--2": true, "ms--1": true, "ms--0": true}]}

  Example request for an asynchronous `test.ping`:

      % curl -sS -i \
              -H 'Content-Type: application/json' \
              -d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"local_async","tgt":"*","fun":"test.ping"}]' localhost:8001

  Example response:

      HTTP/1.0 200 OK
      Content-Length: 103
      Content-Type: application/json

      {"return": [{"jid": "20130412192112593739", "minions": ["ms--4", "ms--3", "ms--2", "ms--1", "ms--0"]}]}

  Example request for looking up a job ID:

      % curl -sS -i \
              -H 'Content-Type: application/json' \
              -d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"runner","fun":"jobs.lookup_jid","jid":"20130412192112593739"}]' localhost:8001

  Example response:

      HTTP/1.0 200 OK
      Content-Length: 89
      Content-Type: application/json

      {"return": [{"ms--4": true, "ms--3": true, "ms--2": true, "ms--1": true, "ms--0": true}]}

form lowstate:

  A list of lowstate data appropriate for the client interface you are calling.

status 200:

  success

status 401:

  authentication required