Varnish Administration Console

Introduction

Varnish Administration Console ships with an inbuilt RESTful API. The goal of the API is to provide a centralised API for accessing and managing all varnish instances. In addition, the API aims to support automation, and ease of testing and verification when managing multiple varnish instances.

This document aims to outline the API in detail. VAC API is built on top of MongoDB and is JSON oriented. The language used in this document will be based on that of NOSQL. For example, table or tuple is referred to as a collection, columns equates to fields, and rows equates to documents. See the SQL to MongoDB Mapping Chart for more details.

Note within the scope of the API, a NOSQL collection is equivalent to an entity, and a NOSQL document is equivalent to an object instance. A model is interchangeable with the term entity, and a model schema is the description of a single entity.

API Reference

HTTP Error Codes

Note that the following status from the vac is common.

Status Description
400 Client request error. Malformed requests. Usual suspect is incorrect JSON syntax or unsupported JSON model, or the API call is disallowed.
401 Unauthorised. Login credential required
402 Invalid or expired license. (Note that when license is in grace mode, an additional header is returned by the vac. e.g. X-VAC-GRACE-LEFT: 1 day(s) left
403 Forbidden, unable to perform the operation. For example, valid user name but no valid session found
404 Not found. wrong URL or id does not exists
405 Method not allowed. Wrong HTTP method used to access the API
415 Unsupported media type. Wrong Content-Type specified by the request
500 Server error. Error derived from the vac itself and users should look into the log files for more details

Unrestricted API

The API is independent from the UI and can be accessed directly from HTTP clients such as curl.

Note that no credentials are needed to access these API.

Unrestricted API is prefixed with the following URI:

/api/rest/

For example, to login, one would issue a POST request with the following Content-Type:

Content-Type: application/x-www-form-urlencoded

The full request with curl would be:

    curl -X POST http://localhost:8080/api/rest/login
	-H "Content-Type: application/x-www-form-urlencoded"
	-d "username=user&password=password"

Restricted API

The API is independent from the UI and can be accessed directly from HTTP clients such as curl.

Restricted API is prefixed with the following URI:

/api/v1/

For example, to issue a ban, one would issue a POST request with the following payload:

    {
	"expression": "req.http.host ~ example.com"
    }

The full request with curl would be:

    curl -u vac:vac -X POST http://localhost:8080/api/v1/group/{group_id}/ban
    -H "Content-Type: application/json"
    -d "{\"expression\":\"req.http.host ~ example.com\"}"