Reactor

API Reference

Basics

Schema

All data is in JSON format.

API Access

The Reactor API is available by default on port 8080. The default endpoints include one that makes this available on port 80 (if nginx is running) but you can choose to expose the API in any way you want.

In this documentation, we will use curl to access the API. You may of course, use any tool or language that you like.

Accept and Content types

Reactor may behave differently depending on the Accept headers. Be sure to use Accept: application/json for programmatic API access.

All data posted to the API should include an approprate Content-Type header, with the value application/json.

API Version

The Reactor API version is obtained by performing an HTTP GET to the root path of the Reactor API.

GET /

Data: none.

Result: {"version": *api-version*}

Example:

curl -i -H 'Accept: application/json' -X GET http://localhost:8000
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 18

`"version": "1.1"`

Reactor uses semantic versioning for the API.

All calls for version v1.1 of the API are available via the path /v1.1/.

Authentication

If you’ve set an authentication key for Reactor, you must pass this as the header X-Auth-Key or as a parameter auth_key. We highly recommended requiring API access through SSL when securing Reactor. (This is possible using the default apihttps endpoint, but you should provide a signed SSL key and certificate).

For example, if you don’t provide the authentication key.

curl -i -H 'Accept: application/json' -X GET http://localhost:8080/v1.1/endpoints
HTTP/1.0 401 Unauthorized
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 12
unauthorized

Then, upon providing the key.

curl -i -H 'Accept: application/json' -H 'X-Auth-Key: bar' -X GET http://localhost:8080/v1.1/endpoints
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 23

`"endpoints": []`

Alternately, providing the key via a query parameter.

curl -i -H 'Accept: application/json' -X GET http://localhost:8080/v1.1/endpoints?auth_key=bar
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 23

`"endpoints": []`

Global Settings

Set Authentication Key

POST /v1.1/auth_key

Data: "auth_key": *authentication-key*

Result: none.

Example:

curl -i --data '`"auth_key": "bar"`' -H 'Content-Type: application/json' -H 'Accept: application/json' -X POST http://localhost:8080/v1.1/auth_key
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Get URL

GET /v1.1/url

Data: none.

Result: {"url": *url*}

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/url
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 25

`"url": "http://example.com"`

Set URL

POST /v1.1/url

Data: {"url": *url*}

Result: none.

Example:

curl -i --data '`"url": "http://example.com"`' -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/v1.1/url
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Get Global Info

These global statistics provide a quick snapshot into the state of the system.

GET /v1.1/info

Data: none.

Result: {"active": *active*, "instances": *instances*, "managers": *managers*, "endpoints": {*state*: *state-count*, ...}

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/info
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 73

`"active": 0, "instances": 0, "endpoints": {"STOPPED": 1}, "managers": 0`

IP Registration

Register IP

POST /v1.1/register/`ip`
POST /v1.1/register

Data: none.

Result: none.

Example:

curl -i -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/v1.1/register/127.0.0.1
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Unregister IP

POST /v1.1/unregister/`ip`
POST /v1.1/unregister

Data: none.

Result: none.

Example:

curl -i -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/v1.1/unregister/127.0.0.1
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Managers

List Manager Configurations

GET /v1.1/managers/configs

Data: none.

Result: [*manager*, ...]

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/managers/configs
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 100

["172.0.0.1", "10.0.2.15", "192.168.1.2", "10.0.3.1", "192.168.122.1"]

List Active Managers

GET /v1.1/managers/active

Data: none.

Result: [*manager*, ...]

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/managers/active
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 39

`["6eaeca66-4992-4353-896c-915897e5f92b"]`

Get Manager Configuration

GET /v1.1/managers/configs/`manager`

Data: none.

Result: The full configuration.

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/managers/configs/127.0.0.1
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 2

`{}`

Get Manager Info

GET /v1.1/managers/active/`manager`

Data: none.

Result: {"name":*name*, "clouds":[*cloud*, ...], "loadbalancers":[*loadbalancer*, ...], ...}

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/managers/active/6eaeca66-4992-4353-896c-915897e5f92b
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 39

`{"name":"127.0.0.1", ...}`

Create or Set Manager Configuration

POST /v1.1/managers/configs/`manager`

Data: The full configuration.

Result: none or validation errors.

Example:

curl -i --data '{}' -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/v1.1/managers/configs/127.0.0.1
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Delete Manager Configuration

DELETE /v1.1/managers/configs/`manager`

Data: none.

Result: none.

Example:

curl -i -H "Accept: application/json" -X DELETE http://localhost:8080/v1.1/managers/configs/127.0.0.1
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Get Manager Log

GET /v1.1/managers/log/`manager`?since=`since`

Data: none.

Result: [[*timestamp*, *severity*, *message*], ...]

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/managers/log/127.0.0.1
TTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 2

[]

Endpoints

List Endpoints

GET /v1.1/endpoints

Data: none.

Result: [*endpoint*, ...]

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 8

["demo"]

Get Endpoint Configuration

GET /v1.1/endpoints/`endpoint`

Data: none.

Result: The full configuration.

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 3207

`...`

Create or Set Endpoint Configuration

POST /v1.1/endpoints/`endpoint`

Data: The full configuration.

Result: none or validation errors.

Example:

curl -i --data '{}' -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/v1.1/endpoints/demo
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Create Endpoint Alias

POST /v1.1/endpoints/`endpoint`/alias

Data: A JSON string with the alias name.

Result: none.

Example:

curl -i --data '"new_name"' -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/v1.1/endpoints/demo/alias
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Delete Endpoint

DELETE /v1.1/endpoints/`endpoint`

Data: none.

Result: none.

Example:

curl -i -H "Accept: application/json" -X DELETE http://localhost:8080/v1.1/endpoints/demo
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

List Endpoint IPs

GET /v1.1/endpoints/`endpoint`/ips
GET /v1.1/endpoint/ips

Data: none.

Result: [*ip*, ...]

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo/ips
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 2

[]

Get Endpoint Log

GET /v1.1/endpoints/`endpoint`/log?since=`since`
GET /v1.1/endpoint/log?since=`since`

Data: none.

Result: [*log-message*, ...]

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo/log
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 2

[]

Get Endpoint Metics

GET /v1.1/endpoints/`endpoint`/metrics
GET /v1.1/endpoint/metrics

Data: none.

Result: {*metric*: *value*, ...}

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo/metrics
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 2

{}

Get Endpoint IP Metrics

GET /v1.1/endpoints/`endpoint`/metrics/`ip`
GET /v1.1/endpoint/metrics/`ip`

Data: none.

Result: {*metric*: [*weight*, *value*], ...}

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo/metrics/127.0.0.1
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 2

{}

Set Endpoint IP Metrics

POST /v1.1/endpoints/`endpoint`/metrics/`ip`
POST /v1.1/endpoint/metrics/`ip`
POST /v1.1/endpoint/metrics

Data: *metric*: [*weight*, *value*], ...

Result: none.

Example:

curl -i --data '`"metric": [1.0, 7.2]`' -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/v1.1/endpoints/demo/metrics/127.0.0.1
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Get Endpoint State

GET /v1.1/endpoints/`endpoint`/state
GET /v1.1/endpoint/state

Data: none.

Result: {"state": <endpoint-state>, "active": [<active-backend>, ...], "manager": <manager-uuid>}

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo/state
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 50

`"active": [], "state": "PAUSED", "manager": null`

List Endpoint Sessions

GET /v1.1/endpoints/`endpoint`/sessions
GET /v1.1/endpoint/sessions

Data: none.

Result: {"*client*:*port*": "*backend*:*port*", ...}

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo/sessions
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 2

{}

Query Endpoint Session

GET /v1.1/endpoints/`endpoint`/sessions/`session`
GET /v1.1/endpoint/sessions/`session`

Data: none.

Result: *backend*:*port*

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo/sessions/127.0.0.1:38743
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 4

null

Drop Endpoint Session

DELETE /v1.1/endpoints/`endpoint`/sessions/`session`
DELETE /v1.1/endpoint/sessions/`session`

Data: none.

Result: none.

Example:

curl -i -H "Accept: application/json" -X DELETE http://localhost:8080/v1.1/endpoints/demo/sessions/127.0.0.1:38273
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

List Endpoint Instances

GET /v1.1/endpoints/`endpoint`/instances
GET /v1.1/endpoint/instances

Data: none.

Result: ["*instance_id*", ...]

Example:

curl -i -H "Accept: application/json" -X GET http://localhost:8080/v1.1/endpoints/demo/sessions
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 2

[]

Associate Endpoint Instance

POST /v1.1/endpoints/`endpoint`/instances/`instance_id`
POST /v1.1/endpoint/instances/`instance_id`

Data: none.

Result: none.

Example:

curl -i -H "Accept: application/json" -X POST http://localhost:8080/v1.1/endpoints/demo/instances/93818b24-ef97-4be4-82f3-1ea494a22fd9
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Disassociate Endpoint Instance

DELETE /v1.1/endpoints/`endpoint`/instances/`instance_id`
DELETE /v1.1/endpoint/instances/`instance_id`

Data: none.

Result: none.

Example:

curl -i -H "Accept: application/json" -X DELETE http://localhost:8080/v1.1/endpoints/demo/instances/93818b24-ef97-4be4-82f3-1ea494a22fd9
HTTP/1.0 200 OK
Server: PasteWSGIServer/0.5 Python/2.7.3
Content-Type: text/html; charset=UTF-8
Content-Length: 0
Reactor is maintained and supported by Gridcentric Inc.