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\"}"