VaaS API

You can use VaaS API to add, edit or remove backends in directors. VaaS Rest API is based on tastypie python library. At the moment of this writing, only json format is supported.

Resources

The following resources are available:

Name	Description	Allowed actions	Allowed commands
Backend	Represents a single node in a service (director)	preview, add, edit, delete
Director	A Varnish director; may represent a SOA service	preview, add, edit, delete
Probe	A health check used to determine backend status	preview, add, edit, delete
Dc	Datacenter	preview, add, edit, delete
Logical Cluster	Cluster of Varnish servers	preview, add, edit, delete	connect-command
Varnish Servers	A Varnish server	preview, add, edit, delete
VCL Template Block	A VCL template block	preview, add, edit, delete
VCL Template	A VCL template	preview, add, edit, delete	vcl-validate-command
Time Profile	Default timeouts profile for director	preview, add, edit, delete
Purger	Purge object from varnishes from a given cluster
Outdated Server	Represents active varnish servers with outdated vcl	preview
Task	Represents state of reloading task - check VaaS Request Flow	preview
Redirect	Represents conditional redirection to particular URL	preview, add, edit, delete	validate-command
DomainMapping	Represents domains representations specific for particular clusters that can be used in redirects	preview, add, edit, delete
Route	Represents conditional routing to desired Director	preview, add, edit, delete	validate-command
RouteConfig	Represents possible request parameters, operators & actions, which can be used in Routes	preview

VaaS resources can be previewed under http://<VaaS instance>/api/v0.1/?format=json

Authentication methods

Authentication is required for all requests except schema. There is only one method of authentication: api key. Credentials for this method (i.e. username and api key) can be passed as query params or as http headers.

To access VaaS API, first generate API key. Click on Welcome, -> Api Key to achieve that.

Sample API requests

All examples below can be tested using VaaS in Docker Compose.

List directors

curl "http://localhost:3030/api/v0.1/director/?username=admin&api_key=vagrant_api_key"

List backends

To list backends located in specified DC belonging to specified Director:

curl "http://localhost:3030/api/v0.1/backend/?director__name=second_service&dc__symbol=dc1&username=admin&api_key=vagrant_api_key"

Create a new Cluster

curl -X POST \
-d '{ "name": "cluster1" }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/logical_cluster/?username=admin&api_key=vagrant_api_key"

Create a new DC

curl -X POST \
-d '{ "name": "dc1", "symbol": "dc1" }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/dc/?username=admin&api_key=vagrant_api_key"

Create a new VCL template

curl -X POST \
-d '{ "version": "4.0", "content": "<VCL/>", "name": "vcl_template_4" }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/vcl_template/?username=admin&api_key=vagrant_api_key"

Call vcl validate command for a new template content

Important remark: the command id (in the below example: 7110e99e-453a-4078-843a-f6c36dd358d2) passed in url should be uniq. The intention of the command is to render new vcl template content, load it into servers connect to vcl template and verify if it will be properly compiled.

curl -X PUT \
-d '{ "content": "<VCL/>"}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/vcl_template/2/vcl-validate-command/7110e99e-453a-4078-843a-f6c36dd358d2/?username=admin&api_key=vagrant_api_key"

expected output

{
  "output": null,
  "pk": "7110e99e-453a-4078-843a-f6c36dd358d2",
  "status": "PENDING",
  "content": "<VCL/>"
}

Verify command result

curl "http://localhost:3030/api/v0.1/varnish_server/connect-command/7110e99e-453a-4078-843a-f6c36dd358d1/?username=admin&api_key=vagrant_api_key"

expected output

{
  "output":  {"is_valid": true, "servers_num": 3},
  "pk": "7110e99e-453a-4078-843a-f6c36dd358d1",
  "status": "SUCCESS",
  "content": "<VCL/>"
}

It's worth mentioning that validation status is passed in output.is_valid, status (SUCCESS) means only that asynchronous validation was processed.

Create a new Probe

curl -X POST \
-d '{ "name": "probe1", "url": "/ts.1", "expected_response": "200" }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/probe/?username=admin&api_key=vagrant_api_key"

Create a new Director

curl -X POST \
-d '{ "name": "director1", "service": "service1", "reachable_via_service_mesh": true, "service_mesh_label": "service1", "service_tag": "www", "probe": "/api/v0.1/probe/1/", "route_expression": "/abc", "cluster": ["/api/v0.1/logical_cluster/1/"], "mode": "round-robin", "time_profile": "/api/v0.1/time_profile/1/" }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/director/?username=admin&api_key=vagrant_api_key"

Create a new Backend and add it to a Director

curl -X POST \
-d '{ "address": "172.17.0.1", "director": "/api/v0.1/director/1/", "dc": "/api/v0.1/dc/1/", "inherit_time_profile": true }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/backend/?username=admin&api_key=vagrant_api_key"

Fetch backend by id

curl -i "http://localhost:3030/api/v0.1/backend/1/?username=admin&api_key=vagrant_api_key"

Update whole backend

curl -i -X PUT \
-d '{
  "address": "192.168.199.34",
  "between_bytes_timeout": "1",
  "connect_timeout": "0.3",
  "dc": {
    "id": 1,
    "name": "First datacenter",
    "resource_uri": "/api/v0.1/dc/1/",
    "symbol": "dc1"
  },
  "director": "/api/v0.1/director/1/",
  "enabled": true,
  "first_byte_timeout": "5",
  "id": 1,
  "inherit_time_profile": true,
  "max_connections": 5,
  "port": 80,
  "resource_uri": "/api/v0.1/backend/1/",
  "status": "Unknown",
  "tags": [],
  "time_profile": {
    "between_bytes_timeout": "1",
    "connect_timeout": "0.3",
    "first_byte_timeout": "5",
    "max_connections": 5
  },
  "weight": 1
}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/backend/1/?username=admin&api_key=vagrant_api_key"

Partially update backend

curl -X PATCH \
-d '{"address": "192.168.199.33"}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/backend/1/?username=admin&api_key=vagrant_api_key"

Create a new Varnish server

curl -X POST \
-d '{ "ip": "172.17.0.7", "hostname": "varnish3", "dc": "/api/v0.1/dc/1/", "port": "6082", "secret": "edcf6c52-6f93-4d0d-82b9-cd74239146b0", "template": "/api/v0.1/vcl_template/1/", "cluster": "/api/v0.1/logical_cluster/1/", "enabled": "True" }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/varnish_server/?username=admin&api_key=vagrant_api_key"

Call connect command for a set of varnishes by passing varnish ids

Important remark: the command id (in the below example: 7110e99e-453a-4078-843a-f6c36dd358d1) passed in url should be uniq. The intention of the command is to connect to each requested active varnish server and return a varnish version or error in the output map. For inactive or maintenance varnishes, the appropriate status will be returned.

curl -X PUT \
-d '{ "varnish_ids": [2,3]}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/varnish_server/connect-command/7110e99e-453a-4078-843a-f6c36dd358d1/?username=admin&api_key=vagrant_api_key"

expected output

{
  "output": null,
  "pk": "7110e99e-453a-4078-843a-f6c36dd358d1",
  "status": "PENDING",
  "varnish_ids": [
    2,
    3
  ]
}

Verify command result

curl "http://localhost:3030/api/v0.1/varnish_server/connect-command/7110e99e-453a-4078-843a-f6c36dd358d1/?username=admin&api_key=vagrant_api_key"

expected output

{
  "output": {
    "2": "varnish-7.0.3",
    "3": "varnish-4.1.11"
  },
  "pk": "7110e99e-453a-4078-843a-f6c36dd358d1",
  "status": "SUCCESS",
  "varnish_ids": [
    2,
    3
  ]
}

Delete a backend

curl -i -X DELETE "http://localhost:3030/api/v0.1/backend/1/?username=admin&api_key=vagrant_api_key"

Patch a list of backends

curl -X PATCH \
-d '{
    "objects": [
    {
      "address": "172.17.0.1",
      "between_bytes_timeout": "1",
      "connect_timeout": "0.5",
      "dc": "/api/v0.1/dc/1/",
      "director": "/api/v0.1/director/1/",
      "enabled": true,
      "first_byte_timeout": "5",
      "id": 1,
      "max_connections": 5,
      "port": 80,
      "resource_uri": "/api/v0.1/backend/1/",
      "status": "Healthy",
      "weight": 1
    },
    {
      "address": "172.17.0.2",
      "between_bytes_timeout": "1",
      "connect_timeout": "0.5",
      "dc": "/api/v0.1/dc/1/",
      "director": "/api/v0.1/director/1/",
      "enabled": true,
      "first_byte_timeout": "5",
      "id": 2,
      "max_connections": 5,
      "port": 80,
      "resource_uri": "/api/v0.1/backend/2/",
      "status": "Healthy",
      "weight": 1
    }
  ]
}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/backend/?username=admin&api_key=vagrant_api_key"

Purge object from varnishes from a given cluster

curl -X POST \
-d '{ "url": "http://example.com/contact", "clusters": "cluster1_siteA_test"  }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/purger/?username=admin&api_key=vagrant_api_key"

Purge object from varnishes from a given cluster with additional request headers (in case of multiple objects in cache because of HTTP Vary header).

VaaS will generate HTTP purge requests for all possible combinations from given headers.

curl -X POST \
-d '{ "url": "http://example.com/contact", "clusters": "cluster1_siteA_test", "headers": {"header1": ["val1", "val2"], "header2": ["val1", "val2"]}  }' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/purger/?username=admin&api_key=vagrant_api_key"

List outdated servers from single logical cluster

curl "http://localhost:3030/api/v0.1/outdated_server/?username=admin&api_key=vagrant_api_key&cluster=clusterA"

Asynchronous create a new Backend and add it to a Director, check reload status

curl -X POST \
-d '{ "address": "172.17.0.1", "director": "/api/v0.1/director/1/", "dc": "/api/v0.1/dc/1/", "inherit_time_profile": true }' \
-H "Content-Type: application/json" \
-H "Prefer: respond-async" \
-v \
"http://localhost:3030/api/v0.1/backend/?username=admin&api_key=vagrant_api_key"

...
< Location: /api/v0.1/task/578d87b6-4dd5-4786-961d-4b3717e616c8/
...

curl -i "http://localhost:3030/api/v0.1/task/578d87b6-4dd5-4786-961d-4b3717e616c8/?username=admin&api_key=vagrant_api_key"

List redirects

curl "http://localhost:3030/api/v0.1/redirect/?username=admin&api_key=vagrant_api_key&format=json"

Create new redirect

curl -X POST \
-d '{"action":"302", "condition": "req.method == \"GET\" && req.url ~ \"/path\"", "src_domain": "example.com", "destination":"/new-path", "preserve_query_params": false, "required_custom_header": false, "priority": 1, "assertions": [{"expected_location": "/new-path", "given_url": "http://example.com"/path"}]}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/redirect/?username=admin&api_key=vagrant_api_key&format=json"

Delete single redirect

curl -X DELETE \
"http://localhost:3030/api/v0.1/redirect/1/?username=admin&api_key=vagrant_api_key&format=json"

Partially update redirect

curl -X PATCH \
-d '{"priority":2}' -H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/redirect/1/?username=admin&api_key=vagrant_api_key&format=json"

Call validate-command for all redirects

curl -X PUT \
-d '{ }' -H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/redirect/validate-command/7110e99e-453a-4078-843a-f6c36dd358d2/?username=admin&api_key=vagrant_api_key"

expected output

{
  "output": null,
  "pk": "7110e99e-453a-4078-843a-f6c36dd358d2",
  "status": "PENDING"
}

Verify command result

curl "http://localhost:3030/api/v0.1/redirect/validate-command/7110e99e-453a-4078-843a-f6c36dd358d1/?username=admin&api_key=vagrant_api_key"

expected output

{
  "output": {
    "pk": "7110e99e-453a-4078-843a-f6c36dd358d2",
    "task_status": "SUCCESS",
    "validation_results": [],
    "validation_status": "PASS"
  },
  "pk": "7110e99e-453a-4078-843a-f6c36dd358d2",
  "status": "SUCCESS"
}

List domain mappings

curl "http://localhost:3030/api/v0.1/domain-mapping/?username=admin&api_key=vagrant_api_key&format=json"

Add static mapping (providing logical cluster(s) resource uri is required)

curl -X POST \
-d'{"clusters": ["/api/v0.1/logical_cluster/1/"], "domain": "static-example.com", "mappings": ["internal-representation.internal"], "type": "static"}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/domain-mapping/?username=admin&api_key=vagrant_api_key&format=json"

Add dynamic mapping (logical clusters are linked dynamically if they have appropriate labels)

curl -X POST \
-d'{"clusters": [], "domain": "dynamic-example.com", "mappings": ["{required-label}.internal"], "type": "dynamic"}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/domain-mapping/?username=admin&api_key=vagrant_api_key&format=json"

List routes

curl "http://localhost:3030/api/v0.1/route/?username=admin&api_key=vagrant_api_key&format=json"

Create new route

curl -X POST \
-d '{"action":"pass", "clusters": ["/api/v0.1/logical_cluster/1/"], "positive_urls": [{"url": "https://example.com/path"}], "condition": "req.http.Host ~ \"example.com\" && req.url ~ \"\/path\"", "director":"/api/v0.1/director/1/", "priority":4}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/route/?username=admin&api_key=vagrant_api_key&format=json"

Delete single route

curl -X DELETE \
"http://localhost:3030/api/v0.1/route/1/?username=admin&api_key=vagrant_api_key&format=json"

Partially update route

curl -X PATCH \
-d '{"action":"pass", "cluster": ["/api/v0.1/logical_cluster/1/"], "condition": "req.http.Host ~ \"example.com\" && req.url ~ \"\/path\"", "director":"/api/v0.1/director/1/", "priority":4}' \
-H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/route/1/?username=admin&api_key=vagrant_api_key&format=json"

Call validate-command for all routes

curl -X PUT \
-d '{ }' -H "Content-Type: application/json" \
"http://localhost:3030/api/v0.1/route/validate-command/7110e99e-453a-4078-843a-f6c36dd358dd/?username=admin&api_key=vagrant_api_key"

expected output

{
  "output": {
    "pk": "7110e99e-453a-4078-843a-f6c36dd358dd",
    "task_status": "PENDING",
    "validation_results": null,
    "validation_status": null
  },
  "pk": "7110e99e-453a-4078-843a-f6c36dd358dd",
  "status": "PENDING"
}

Verify command result

curl "http://localhost:3030/api/v0.1/route/validate-command/7110e99e-453a-4078-843a-f6c36dd358dd/?username=admin&api_key=vagrant_api_key"

expected output

{
  "output": {
    "pk": "7110e99e-453a-4078-843a-f6c36dd358dd",
    "task_status": "SUCCESS",
    "validation_results": [
      {
        "current": {
          "director": {
            "id": 2,
            "name": "second_service"
          },
          "route": {
            "id": 1,
            "name": "req.url ~ \"^\\/flexibleee\""
          }
        },
        "error_message": "",
        "expected": {
          "director": {
            "id": 2,
            "name": "second_service"
          },
          "route": {
            "id": 1,
            "name": "req.url ~ \"^\\/flexibleee\""
          }
        },
        "result": "PASS",
        "url": "http://192.168.199.4:6081/flexibleee"
      }
    ],
    "validation_status": "PASS"
  },
  "pk": "7110e99e-453a-4078-843a-f6c36dd358dd",
  "status": "SUCCESS"
}

Examine route config

curl "http://localhost:3030/api/v0.1/route_config/?username=admin&api_key=vagrant_api_key&format=json"

Explore more

Detailed information about interaction with api based on tastypie can be found here.