Introduction

Principle of Operation

In this document, to set means to create or update an object. Objects are both created and updated using the http put method and every request is idempotent. Set operations typically return 204 No Content on success, unless otherwise specified. This also means that to update an attribute on an object you need to post the complete object.

Operations that are described as get will return a single JSON object. Operations that are described as list will instead return a JSON array of objects. In both cases the expected successful status is 200 OK with other codes indicating an error.

All delete operations use the http delete method and return 204 No Content on success. Delete operations are not idempotent, in that they will instead return 404 Not Found if the object to be deleted does not exist. The client may choose to interpret this as success in that the object in question does not exist after the operation.

All data exchanged is in JSON format. All attribute names follow the lowerCamelCase convention.

It is useful to use the arigi CLI when exploring the REST API. Specifically, running arigi --api-verbose ...any command... will show, in addition to the command results, the exact operations performed, data sent, and data received.

Data Model

Arigi uses an internal data model based on the following objects:

Devices:

represent Syncthing instances. These are identified by their (Syncthing) device ID, and must have an API key and API port.

Templates:

contain configuration fragments that can be evaluated and applied to devices.

Tags:

can be attached to devices and templates in order to tie them together.