API Reference¶

Vulcan’s HTTP API is the best way to configure one or several instances of Vulcan at the same time. Essentially it’s a tiny wrapper around the backend. Multiple Vulcand instances listening to the same prefix would detect changes simultaneously and reload configuration.

Status¶

Status endpoint is handy when you need to integrate Vulcand with another load balancer that can poll Vulcand to route the traffic based on the healthcheck response.

Check status¶

GET /v2/status

Returns: 200 OK

{
   "Status": "ok"
}

Log severity¶

Log severity endpoint allows to change the logging severity for a running instance

Get severity¶

GET /v2/log/severity

Returns: 200 OK

{
   "Severity": "WARN"
}

Set severity¶

PUT 'multipart/form-data' /v1/log/severity

Parameter	Description
severity	Severity - `WARN`, `INFO` or `ERROR`

Returns: 200 OK

{
   "Message": "Severity has been updated to INFO"
}

Host¶

Get hosts¶

GET /v2/hosts

Example response:

{
  "Hosts":[
     {
        "Name":"localhost",
        "Settings":{
           "KeyPair":null,
           "Default":false
        }
     }
  ]
}

Upsert host¶

POST 'application/json' /v2/hosts

Add a host to the proxy.

{
"Host": {
 "Name": "localhost",                              // hostname
 "Settings": {                                     // settings are optional
   "KeyPair": {"Cert": "base64", Key: "base64"},   // base64 encoded key-pair certficate
   "Default": false ,                              // default host for SNI
 }
}

}

Example responses:

{
 "Name": "localhost",
 "Settings": {
   "KeyPair": null,
   "Default": false
 }
}

Delete host¶

DELETE /v2/hosts/<name>

Delete a host.

Listener¶

Upsert listener¶

POST 'application/json' /v2/listeners

Upsert listener

{
 "Listener": {
  "Id": "l1",
  "Protocol": "https", // http or https
  "Address":
    {
       "Network":"tcp", // unix or tcp
       "Address":"localhost:8184"
    }
 }
}

Example response:

{
  "Id": "12",
  "Protocol": "https",
  "Address":
    {
       "Network":"tcp",
       "Address":"localhost:8184"
    }
}

Delete listener¶

DELETE /v2/listeners/<listener-id>

Delete a listener

Backend¶

Get backends¶

GET /v2/backends

Retrieve the existing upstreams. Example response:

{
 "Backends": [
   {
     "Id": "b1",
     "Type": "http",
     "Settings": {
       "Timeouts": {
         "Read": "",
         "Dial": "",
         "TLSHandshake": ""
       },
       "KeepAlive": {
         "Period": "",
         "MaxIdleConnsPerHost": 0
       }
     }
   }
 ]
}

Upsert backend¶

POST 'application/json' /v2/backends

{
"Backend": {
  "Id": "b1",
  "Type": "http",
  "Settings": {
    "Timeouts": {
      "Read": "5s",
      "Dial": "5s",
      "TLSHandshake": "10s"
    },
    "KeepAlive": {
      "Period": "30s",
      "MaxIdleConnsPerHost": 12
    }
  }
 }
}

Example response:

{
 "Id": "b1",
 "Type": "http",
 "Settings": {
   "Timeouts": {
     "Read": "5s",
     "Dial": "5s",
     "TLSHandshake": "10s"
   },
   "KeepAlive": {
     "Period": "30s",
     "MaxIdleConnsPerHost": 12
   }
 }
}

Delete backend¶

DELETE /v2/backends/<id>

Server¶

Get servers¶

GET /v2/backends/<id>/servers

Retrieve the servers of the backend. Example response:

{
 "Servers": [
   {
     "Id": "srv1",
     "URL": "http://localhost:5000"
   },
   {
     "Id": "srv2",
     "URL": "http://localhost:5003"
   }
 ]
}

Get server¶

GET /v2/backends/<id>/servers/<server-id>

Retrieve the particular server with id server-id

Upsert endpoint¶

POST /v1/upstreams/<id>/endpoints

Upsert server to the backend

{
 "Server": {
   "Id": "srv1",
   "URL": "http://localhost:5000"
 }
}

Example response:

{
  "Id": "e4",
  "Url": "http://localhost:5004",
  "Stats": null
}

Delete server¶

DELETE /v2/backends/<id>/servers/<server-id>

Delete a server.

Frontend¶

Get frontends¶

GET /v2/frontends

Retrieve the frontends. Example response:

{
 "Frontends": [
   {
     "Id": "f1",
     "Route": "Path(`/`)",
     "Type": "http",
     "BackendId": "b1",
     "Settings": {
       "Limits": {
         "MaxMemBodyBytes": 0,
         "MaxBodyBytes": 0
       },
       "FailoverPredicate": "",
       "Hostname": "",
       "TrustForwardHeader": false
     }
   }
 ]
}

Get frontend¶

GET /v2/frontends/<frontend-id>

Retrieve the particular frontend with id frontend-id

{
 "Id": "f1",
 "Route": "Path(`/`)",
 "Type": "http",
 "BackendId": "b1",
 "Settings": {
   "Limits": {
     "MaxMemBodyBytes": 0,
     "MaxBodyBytes": 0
   },
   "FailoverPredicate": "",
   "Hostname": "",
   "TrustForwardHeader": false
 }
}

Upsert frontend¶

POST 'application/json' /v1/hosts/<hostname>/frontends

Add a frontend to the host. Params:

{
 "Frontend": {
   "Id": "f1",
   "Route": "Path(`\/`)",
   "Type": "http",
   "BackendId": "b1",
   "Settings": {
     "Limits": {
       "MaxMemBodyBytes": 0,
       "MaxBodyBytes": 0
     },
     "FailoverPredicate": "",
     "Hostname": "",
     "TrustForwardHeader": false
   }
 }
}

Example response:

{
 "Id": "f1",
 "Route": "Path(`/`)",
 "Type": "http",
 "BackendId": "b1",
 "Settings": {
   "Limits": {
     "MaxMemBodyBytes": 0,
     "MaxBodyBytes": 0
   },
   "FailoverPredicate": "",
   "Hostname": "",
   "TrustForwardHeader": false
 }
}

Delete frontend¶

DELETE /v2/frontends/<frontend-id>

Delete a frontend.

Rate limit¶

Get rate limit¶

GET /v2/frontends/<frontend-id>/middlewares/<middleware-id>

Retrieve the particular rate of frontend with id frontend-id and rate id rate-id Example response:

{
  "Id": "rl1",
  "Priority": 0,
  "Type": "ratelimit",
  "Middleware": {
    "PeriodSeconds": 1,
    "Burst": 3,
    "Variable": "client.ip",
    "Requests": 1
  }
}

Upsert rate limit¶

POST 'application/json' /v2/frontends/middlewares

Add a rate limit to the frontend, will take effect immediately.

{
 "Middleware": {
   "Id": "rl1",
   "Priority": 0,
   "Type": "ratelimit",
   "Middleware": {
     "PeriodSeconds": 1,
     "Burst": 3,
     "Variable": "client.ip",
     "Requests": 1
   }
 }
}

Json parameters explained:

Parameter	Description
Id	Optional rate id, will be generated if omitted
Requests	Required amount of allowed requests
PeriodSeconds	Required period in seconds for counting the requests
Burst	Required allowed burst of the requests (additional requests exceeding the rate)
Variable	Variable for rate limiting e.g. client.ip or request.header.My-Header

Delete a rate limit¶

DELETE /v2/frontends/<frontend-id>/middlewares/<middleware-id>

Deletes rate limit from the frontend.

Connection limit¶

Get connection limit¶

GET /v2/frontends/<frontend-id>/middlewares/<conn-id>

Retrieve the particular connection limit of frontend with id frontend-id and connection limit id conn-id. Example response:

{
  "Id": "cl1",
  "Priority": 0,
  "Type": "connlimit",
  "Middleware": {
    "Connections": 3,
    "Variable": "client.ip"
  }
}

Upsert connection limit¶

POST 'application/json' /v2/frontends/<frontend>/middlewares

Upsert a connection limit to the frontend. Example response:

{
 "Middleware": {
  "Id": "cl1",
  "Priority": 0,
  "Type": "connlimit",
  "Middleware": {
    "Connections": 3,
    "Variable": "client.ip"
  }
 }
}

JSON parameters explained

Parameter	Description
Id	Optional limit id, will be generated if omitted.\|
Connections	Required maximum amount of allowed simultaneous connections\|
Variable	Variable for limiting e.g. `client.ip` or `request.header.My-Header`

Delete connection limit¶

DELETE /v2/frontends/<frontend-id>/middlewares/<conn-id>

Delete a connection limit from the frontend.