🛋️ Laterna (Server)

Laterna is a lightweight REST api for sharing HEX color codes between 2 (or more) lamps with simple HTTP requests, written in go.

Note

This project was developed with my own use case in mind. Expect bugs and weird annoyances/limitations, as this is my first REST api and my first time using go

Setup

1. Clone the repository

git clone https://github.com/siestaw/laterna.git
cd laterna

2. Configure the server

Laterna requires a config.json in it's root directory. An example config is provided

$ mv config.json.example config.json

You can leave the json as it is or configure it to your liking, although some configuration options (e.g. verboseLogging) aren't fully implemented yet.

3. Run

Make sure that go is installed. The server was tested with go 1.24.5 on linux.

$ go run ./cmd/server

or use the makefile:

$ make run

🛜 API Documentation

Docs

Base URL

http://your-server.com/api/v1

---

Authentification

The admin token will be displayed once while starting for the first time. To generate a new one, run with the --resetAdminToken flag.

All endpoints require the admin token in the header of the request:

Authorization: <token>

---

Routes

Controller

Method	Route	Description	Request Body
POST	/controllers	Create a new controller	—
DELETE	/controllers	Delete an existing controller	{ "ID": 1 }

---

Colors

Method	Route	Description	Request Body
GET	/colors/	Get the current color of all available controllers	—
GET	/colors/{id}	Get the current color of a specific controller	—
PUT	/colors/{id}	Set the color of a controller	{ "color": "#FF0000" }

---

cURL examples

Create a new controller

$ curl -X POST http://your-server.com/api/v1/controllers \
       -H "Authorization: $TOKEN"

ℹ️ Response with the newly assigned ID. The ID will always be the next available one

Delete a controller

$ curl -X DELETE localhost:8080/api/v1/controllers \
       -H "Authorization: $TOKEN" \
       -d '{"ID": 1}'

Get the current color of all controllers

$ curl -X GET localhost:8080/api/v1/colors/ \
       -H "Authorization: $TOKEN"

Get the current color of a specific controller

$ curl -X GET localhost:8080/api/v1/colors/1 \
       -H "Authorization: $TOKEN"

Set the color of a controller

$ curl -X PUT localhost:8080/api/v1/colors/1 \
       -H "Authorization:$TOKEN" \
       -d '{"Color": "#C2C342"}'