Skip to content

REST API documentation

Jump to bottom Edit New page
Rad Gruchalski edited this page Jan 22, 2015 · 5 revisions

The main means of communication with the gossiperl daemon is via embedded REST API. This page provides an overview of available calls with cURL examples.

Credentials explained

  • $SUPER_USER:$SUPER_PASS: top user credentials; these should not be shared even with applications; these credentials allow manipulating every overlay running within gossiperl
  • $REST_USER:$REST_PASS: credentials used to list overlays and create new overlays
  • $OVERLAY_NAME:$OVERLAY_TOKEN: overlay specific credentials; use these to modify an overlay or get any information about an overlay; every overlay has its own separate set of these

Overlay token

Once an overlay has been created with a REST request, an overlay token is returned. The value can be found in 2 places: x-session-token header of the overlay creation request and a token field of the body. Any subsequent calls to any operation modifying or describing data of that overlay has to be executed with that token.

Authenticate overlay requests

There are 2 methods of authenticating overlay requests - basic authentication and x-session-token header. The following are valid:

curl ... -u $OVERLAY_NAME:$OVERLAY_TOKEN ...
# and
curl ... -H 'X-Session-Token: $OVERLAY_TOKEN' ...

$OVERLAY_TOKEN is the token returned by overlay creation request. $OVERLAY_NAME in case of basic authentication is the name of the overlay for which the operation is executed, for example, for: GET /membership/my_overlay the value of $OVERLAY_NAME is my_overlay.

Standard errors:

  • 401: authentication required
  • 405: request method not supported

Create an overlay

POST /overlays/:overlay_name: Create an overlay with a given name. The body of the request contains configuration of the overlay. All configurable options explained in Overlay configuration.

Example request:

curl -i -k -u $REST_USER:$REST_PASS \
  -X POST \
  -H 'Contetnt-Type: application/json; charset=utf-8' -d '{
  "ip": "0.0.0.0",
  "port": 6666,
  "rack_name":
  "dev_rack1",
  "racks": { "dev_rack1": ["192.168.50.100"] } ,
  "symmetric_key": "v3JElaRswYgxOt4b"
}' https://192.168.50.100:8080/overlays/gossiper_overlay_remote

Response:

HTTP/1.1 201 Created
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 136
content-type: application/json; charset=utf-8
x-session-token: 3a2ccfa1-44c5-49f1-af82-f934627c654d

{"token":"3a2ccfa1-44c5-49f1-af82-f934627c654d","overlays":["gossiper_overlay_remote"],"operation":"add_overlay","timestamp":1417714618}

Success: 201 Created.

Errors:

  • 409: overlay with a given name already present
  • 412: no seeds in racks information for given rack_name
  • 412: REST credentials not configured
  • 500: internal error

List overlays

GET /overlays: list gossiperl overlays

Example request:

curl -i -G -k -u $REST_USER:$REST_PASS \
  -H 'Contetnt-Type: application/json; charset=utf-8' \
  https://192.168.50.100:8080/overlays

Response:

HTTP/1.1 200 OK
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 86
content-type: application/json; charset=utf-8

{"overlays":["gossiper_overlay_remote"],"operation":"overlays","timestamp":1417714618}

Success: 200 OK.

Errors:

  • 412: REST credentials not configured

List web tokens

GET /tokens: get tokens for all installed overlays, requires superuser credentials.

Example request:

curl -i -k -u $SUPER_USER:$SUPER_PASS \
  -H 'Contetnt-Type: application/json; charset=utf-8'
  https://192.168.50.100:8080/tokens

Response:

HTTP/1.1 200 OK
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 123
content-type: application/json; charset=utf-8

{"tokens":[{"gossiper_overlay_remote":"356780ec-71ef-40dc-a855-22dd3af1967f"}],"operation":"tokens","timestamp":1417714618}

Success: 200 OK.

Errors:

  • 412: superuser credentials not configured

Get overlay configuration

GET /configuration/:overlay_name: get overlay configuration, a number of configuration properties are shown as protected, these can not be loaded back.

Example request:

curl -i -G -k -u $OVERLAY_NAME:$OVERLAY_TOKEN \
  -H 'Contetnt-Type: application/json; charset=utf-8' \
  https://192.168.50.100:8080/configuration/gossiper_overlay_remote

Response:

HTTP/1.1 200 OK
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 679
content-type: application/json; charset=utf-8

{"configuration":
  {"member_name":"gossiper_overlay_remote0.0.0.0:6666@8dfc3704-6577-4669-9582-4a1774711550",
   "ip":"0.0.0.0",
   "port":6666,
   "ip_hint":"undefined",
   "iface":"undefined",
   "rack_name":"dev_rack1",
   "racks":{"dev_rack1":["192.168.50.100"]},
   "quarantine_after":20,
   "max_quarantined":10,
   "drop_unreachable_after":180,
   "redelivery_retry_max":0,
   "redelivery_retry_every":5,
   "check_local_state_every":2,
   "drop_stale_subscriptions_after":20,
   "incoming_data_buffer_size":16777216,
   "outgoing_data_buffer_size":16777216,
   "read_packet_count":5,
   "secret":"protected",
   "symmetric_key":"protected"},
  "operation":"configuration",
  "overlay":"gossiper_overlay_remote",
  "timestamp":1417714618}

Success: 200 OK.

Errors:

  • 404: overlay not found

Get membership information

GET /membership/:overlay_name: get members of an overlay with their statuses and heartbeats.

Example request:

curl -i -G -k -u $OVERLAY_NAME:$OVERLAY_TOKEN \
  -H 'Contetnt-Type: application/json; charset=utf-8' \
  https://192.168.50.100:8080/membership/gossiper_overlay_remote

Response:

HTTP/1.1 200 OK
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 576
content-type: application/json; charset=utf-8

{"membership":[
 {"name":"gossiper_overlay_remote0.0.0.0:6666@7dfe5e65-5594-481e-b58c-4726cf1b65b9",
  "state":"reachable",
  "ip":"0.0.0.0",
  "port":6666,
  "heartbeat":1417714618},
 {"name":"gossiper_overlay_remote0.0.0.0:6666@1ded3e50-aa5a-4344-82b2-80989e5a0245",
  "state":"reachable",
  "ip":"192.168.50.101",
  "port":6666,
  "heartbeat":1417714618},
 {"name":"gossiper_overlay_remote0.0.0.0:6666@f32f2fcd-5ef5-4822-803a-16ad09088292",
  "state":"reachable",
  "ip":"192.168.50.102",
  "port":6666,
  "heartbeat":1417714617}],
 "operation":"membership",
 "overlay":"gossiper_overlay_remote",
 "timestamp":1417714618}

Success: 200 OK.

Errors:

  • 404: overlay not found

Get statistics

GET /statistics/:overlay_name[/:window]: get overlay statistics for a given time window. Supported windows: total, 1d, 12h, 6h, 3h, 1h, 30m, 10m and 1m. Default window is total.

Example request:

curl -i -G -k -u $OVERLAY_NAME:$OVERLAY_TOKEN \
  -H 'Contetnt-Type: application/json; charset=utf-8' \
  https://192.168.50.100:8080/statistics/gossiper_overlay_remote

HTTP/1.1 200 OK
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 1011
content-type: application/json; charset=utf-8

{"overlay":"gossiper_overlay_remote",
 "window":"total",
 "enabled":true,
 "statistics":"{\"digest-in\":{\"sum_packets\":6655,\"total_size\":1444864.0},\"digest-out\":{\"sum_packets\":4368,\"total_size\":1118208.0},\"digestAck-in\":{\"sum_packets\":3791,\"total_size\":2074112.0},\"digestAck-out\":{\"sum_packets\":6556,\"total_size\":3141824.0},\"digestEnvelope-out\":{\"sum_packets\":1,\"total_size\":160},\"digestEvent-out\":{\"sum_packets\":2,\"total_size\":384},\"digestForwardableTest-in\":{\"sum_packets\":1,\"total_size\":128},\"digestForwardedAck-in\":{\"sum_packets\":1,\"total_size\":160},\"digestForwardedAck-out\":{\"sum_packets\":1,\"total_size\":256},\"digestSubscribe-in\":{\"sum_packets\":5,\"total_size\":960},\"digestSubscribeAck-out\":{\"sum_packets\":4,\"total_size\":640},\"digestSubscriptions-out\":{\"sum_packets\":1225,\"total_size\":548800},\"digestUnsubscribe-in\":{\"sum_packets\":1,\"total_size\":192},\"digestUnsubscribeAck-out\":{\"sum_packets\":1,\"total_size\":160}}",
 "ts":1417714618}

Success: 200 OK.

Errors:

  • 404: overlay not found
  • 412: requested window not supported

Change configuration

POST /overlays/:overlay_name: update full configuration.

POST /overlays/:overlay_name/:property: update single property.

There are two possibilities for changing overlay configuration. Either, the whole configuration can be replaced at one or a single property can be amended. Any option described as available to set in Overlay configuration.

Full configuration, example request:

curl -i -k -X POST \
  -H 'Contetnt-Type: application/json; charset=utf-8' \
  -H 'X-Session-Token: 15454d13-f9ed-43a7-952f-b1e61b20fdba' \
  -d '{
    "ip": "0.0.0.0",
    "port": 6666,
    "symmetric_key": "v3JElaRswYgxOt4b",
    "iv": "wEKzHIGQDTdLknUE" }' \
  https://192.168.50.101:8080/overlays/gossiper_overlay_remote

Response: Same as GET /configuration/:overlay_name response.

Single property, example request:

curl -i -k -X PUT \
  -H 'Contetnt-Type: application/json; charset=utf-8' \
  -H 'X-Session-Token: 15454d13-f9ed-43a7-952f-b1e61b20fdba' \
  -d '{"dev_rack1":["192.168.50.100", "192.168.50.200"]}' \
https://192.168.50.101:8080/overlays/gossiper_overlay_remote/racks

Response: Same as GET /configuration/:overlay_name response.

Success: 202 Accepted.

Errors:

  • 400: given JSON is not valid
  • 404: overlay not found

Delete and overlay

DELETE /overlays/:overlay_name: remove an overlay

Example request:

curl -i -k -u $OVERLAY_NAME:$OVERLAY_TOKEN \
  -X DELETE -H 'Contetnt-Type: application/json; charset=utf-8' \
  https://192.168.50.100:8080/overlays/gossiper_overlay_remote

Response:

HTTP/1.1 202 Accepted
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 67
content-type: application/json; charset=utf-8

{"overlays":[],"operation":"remove_overlay","timestamp":1417714618}

Success: 202 Accepted.

Errors:

  • 404: overlay not found
  • 409: could not stop an overlay due to an internal error, possibly already stopping

Sending digests

Apart from a standard way of sending arbitrary digests via the Thrift gossiperl API, it is also possible to send these via the REST API.

POST /digest/:overlay_name: send an arbitrary digest via the REST API.

Example requests:

Send a digest to local subscribers of a node only:

curl -i -k -X POST \
  -H 'Contetnt-Type: application/json; charset=utf-8'
  -H 'X-Session-Token: 15454d13-f9ed-43a7-952f-b1e61b20fdba'
  -d '{
    "digestForwardableTest": [{
                              "some_data": "some data to send",
                              "string": 1 }],
    "recipient_ip": "192.168.50.100",
    "recipient_port": 6666 }' \
  https://192.168.50.101:8080/digest/gossiper_overlay_remote

Send a digest and forward across the whole overlay (no recipient details):

curl -i -k -X POST \
  -H 'Contetnt-Type: application/json; charset=utf-8' \
  -H 'X-Session-Token: b2c65a77-8a16-40ed-bbaa-18b225c197ee'
  -d '{
    "digestForwardableTest": [{
                              "some_data": "some data to send",
                              "string": 1 }] }' \
https://192.168.50.101:8080/digest/gossiper_overlay_remote

Response (both cases):

HTTP/1.1 202 Accepted
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 15
content-type: application/json; charset=utf-8

{"status":"ok"}

Success: 202 Accepted.

Errors:

  • 400: given JSON is not valid
  • 404: overlay not found
  • 409: incomplete body, no digest_type with data given as minimum

Listing subscriptions

GET /subscriptions/:overlay_name: list subscriptions on an overlay, lists remote and local subscriptions.

Example request:

curl -i -G -k -u $OVERLAY_NAME:$OVERLAY_TOKEN \
  -H 'Contetnt-Type: application/json; charset=utf-8' \
  https://192.168.50.100:8080/subscriptions/gossiper_overlay_remote

Response:

HTTP/1.1 200 OK
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 442
content-type: application/json; charset=utf-8

{"subscriptions":[
 {"event_type":"digestForwardableTest",
  "member_name":"client-test",
  "origin":"gossiper_overlay_remote0.0.0.0:6666@37d24c32-9ec3-46cf-aa86-a58930d0727b",
  "heartbeat":1417714618},
 {"event_type":"member_in",
  "member_name":"client-test",
  "origin":"gossiper_overlay_remote0.0.0.0:6666@37d24c32-9ec3-46cf-aa86-a58930d0727b",
  "heartbeat":1417714617}],
 "operation":"subscriptions",
 "overlay":"gossiper_overlay_remote",
 "timestamp":1417714618}

Success: 200 OK.

Errors:

  • 404: overlay not found

Force service reconfiguration

POST /reconfigure: reload configuration from the /etc/gossiperl/settings.json file. REST credentials and superuser credentials are loaded from application settings on every request so these can also be changed and reloaded.

Example request:

curl -i -k -u $SUPER_USER:$SUPER_PASS \
  -X POST -H 'Contetnt-Type: application/json; charset=utf-8' \
  https://192.168.50.100:8080/reconfigure

Response:

HTTP/1.1 202 Accepted
connection: keep-alive
server: Cowboy
date: Thu, 04 Dec 2014 17:36:58 GMT
content-length: 74
content-type: application/json; charset=utf-8

{"status":"reconfigured","operation":"reconfigure","timestamp":1417714618}

Success: 202 Accepted if settings.json exists.
Success: 200 Accepted if settings.json does not exist.

Errors:

  • 500: there was an error while reading or parsing the configuration; check if settings.json is valid
Add a custom footer
Add a custom sidebar
Clone this wiki locally