10.1. OliveTin API Overview

This section of the documentation is intended for developers, and those who want to hack around with OliveTin and extend it. This page provides a few pointers to get started.

Short version: http://olivetinServer:1337/api for the REST API. Swagger documents the API.

Longer version: The OliveTin API is formally defined using the Protobuf IDL, which generates gRPC stubs, as well as a REST Gateway.

The REST API gateway is used by the WebUI, and you can use it too by default - it is exposed at "/api" by default.

The gRPC API only listens on localhost default, but it can be set to listen publicly. See the network ports documentation for a better description of how the APIs are exposed. Most people do not need to use the gRPC API.

10.1.1. Example API call: Start an action

user@host: curl -X POST "http://olivetin.webapps.teratan.lan/api/StartAction" -d '{"actionName": "Nuclear reactor shutdown"}'
PS C:\Users\xcons> $json = '{"actionName": "Deploy attack Gnomes"}'
PS C:\Users\xcons> Invoke-RestMethod -Method "Post" -Uri "http://olivetinServer:1337/api/StartAction" -Body $json

10.1.2. Example API call: Start an action with arguments

user:host: curl -X POST 'http://olivetin.example.com/api/StartAction' -d '{"actionName": "Ping host", "arguments": [{"name": "host", "value": "example.com"},{"name": "count", "value": "1"}]}'

10.1.3. Example API call: Get the dashboard buttons ("components")

user@host: curl http://olivetinServer:1337/api/GetDashboardComponents

Please do talk to the developers on Discord if you’d like help using the API, or you’re thinking about building something interesting using the API!