Using the Vamp API
The HTTP API supports websockets. Further details coming soon.
Vamp has one REST API. This page explains how to specify pagination, and json and yaml content types, and how to effectively use the Vamp REST API.
- Vamp requests can be in YAML format or JSON format. Set the
Content-Typerequest header to
- Vamp responses can be in YAML format or JSON format. Set the
Acceptrequest header to
Vamp API endpoints support pagination with the following scheme:
- Request parameters
page(starting from 1, not 0) and
per_page(by default 30) e.g:
- Response headers
X-Total-Countgiving the total amount of items (e.g. 349673) and a
Linkheader for easy traversing, e.g.
X-Total-Count: 5522 Link: <http://vamp:8080/api/v1/events/get?page=1&per_page=5>; rel=first, <http://vamp:8080/api/v1/events/get?page=1&per_page=5>; rel=prev, <http://vamp:8080/api/v1/events/get?page=2&per_page=5>; rel=next, <http://vamp:8080/api/v1/events/get?page=19&per_page=5>; rel=last
See Github’s implementation for more info.
- Create & Delete operations are idempotent: sending the second request with the same content will not result to an error response (4xx).
- An update will fail (4xx) if a resource does not exist.
- A successful create operation has status code 201
Createdand the response body contains the created resource.
- A successful update operation has status code 200
Acceptedand the response body contains the updated resource.
- A successful delete operation has status code 204
No Contentor 202
Acceptedwith an empty response body.
Send multiple resources
It is possible to
DELETE YAML or JSON documents containing more than one artifact definition.
Artifacts of the same type can be grouped together and sent to a specific endpoint, such as
/api/v1/breeds. Different artifact types can also be grouped together and sent to the general API endpoint
api/v1 by including a
kind field in each artifact definition. The artifact kind corresponds to the singular form of the artifact type (for example
Example (YAML) - post multiple artifacts to a specific endpoint
--- name: ... # breed 1 definition ... --- name: ... # breed 2 definition .... --- name: ... # breed 3 definition ....
Example (YAML) - post multiple artifact types to /api/v1
When using the general
api/v1 endpoint, each artifact description must include a
--- name: ... kind: blueprint # blueprint definition ... --- name: ... kind: breed # breed definition ... --- name: ... kind: condition # condition definition ...