SearchVarnish Controller
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).