API

The API for Varnish Controller is built as a RESTful HTTP API. Requests will respond with status code that explains the status of the request. In most error cases an ErrorMsg struct will be included in the body, explaining the details of the failed query. In other cases the response body might include the object requested/created.

Swagger (OpenAPI) generated documentation can be found on the API-GW endpoint, e.g. http://localhost:8002/docs/. This presents all available API paths and responses. There are however some caveats about how to use the API:

All requests must present the current state of how the resource should look. The API does not support partial updates. Hence, posting a list of tags {"Tags":[{"ID": 1}, {"ID": 2}]} will result in those tags for the given object. It will not be appended.
All calls require the ID for an existing object. That is {"ID": 1} will specify a specific object. It cannot be specified by giving a different attribute such as name. The swagger documentation is automatically generated and shows more information than ID for PUT/POST requests. Extra attributes will be ignored.
API version is in the path (e.g. http://localhost/api/v1/agents).
Varnish Controller API supports two versions. Current version and previous version. The previous version is marked with a Warning header including a deprecation notice. The previous version will be removed on the next updated API version. If version v1 and v2 exists, v1 would be deprecated but still possible to use. Once version v3 is released, versionv1 will be removed and versionv2 would be marked as deprecated.
Nothing will be removed or changed in an API version, only appended. New endpoints, new models, appended attributes to models, may be added to an existing API version. Removal of models, attributes, paths etc. are only performed after removing previously deprecated API versions.
The API supports sorting by adding the sort query parameter with the format sort=<column>[:desc|asc] (e.g. sort=id:asc, sort by id in ascending order).
The API also support pagination by adding the take query parameter with the format take=<limit>[,offset] (e.g. take=5,10, select 5 elements starting at position 10).