🛋️ Laterna (Server)

Laterna is a simple and lightweight REST API for viewing and setting HEX color codes over the web, written in go.

Note

This project was developed with my own use case in mind. This is my first time building a REST API and my first time utilizing the go language. Expect bugs and weird annoyances/limitations

⚙️ Setup

1. Clone the repository

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

2. Configure the server

Laterna requires a config.json file in the root directory. A example config is provided

cp config.json.example config.json

You can leave the config as it is or adjust it to your liking.

Make sure that your firewall supports connections to the configured port for laterna (default: 8080), otherwise clients won't be able to connect to the API. You can do so by using ufw on most linux distributions

sudo ufw allow 8080/tcp
sudo ufw reload

Of course, you'll have to change 8080 to your desired port if configured otherwise

3. Run

Make sure that go is installed (tested with Go 1.24.5 on Linux)

make run
# OR
go run ./cmd/server/

For advanced Makefile options:

make help

🛜 API Documentation

🔑 Authentication

All requests require the admin token via the Authorization header:

Authorization: <token>

The token is shown once on the first startup. To regenerate it, run the server with:

./laterna --resetAdminToken

---

📦️ Endpoints

🎛️ Controllers

Method	Route	Description	Payload
POST	/controllers	Create a new controller
POST	/controllers/toggle/{id}	Toggle an existing controller on/off
DELETE	/controllers/{id}	Delete an existing controller

🎨 Colors

Method	Route	Description	Payload
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": "#FFFFFF}

---

Request examples

📥️ HTTPie examples

Create a new controller

$ http POST localhost:8080/api/v1/controllers "Authorization: $TOKEN"

Delete the controller with the ID of 1

$ http DELETE localhost:8080/api/v1/controllers/1 "Authorization: $TOKEN"

Get every controllers colors

$ http GET localhost:8080/api/v1/colors/ "Authorization: $TOKEN"

Get color of the controller with the ID of 1

$ http GET localhost:8080/api/v1/colors/1 "Authorization: $TOKEN"

Set the color of the controller with the ID of 1

$ http PUT localhost:8080/api/v1/colors/1 "Authorization: $TOKEN" Color="#C2C342"

Toggle the controller with the ID 1 on/off

$ http PUT localhost:8080/api/v1/colors/1 "Authorization: $TOKEN"

📥️ cURL examples

Create a new controller

$ curl -X POST localhost:8080/api/v1/controllers \
       -H "Authorization: $TOKEN"

Delete a controller

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

Get every controllers colors

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

Get a specific controllers's color

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

Set a controller's color

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

Toggle controller on/off

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

---

📤️ Response Format

All responses follow this format:

{
    "data": {
        "color": "#C16A31",
        "id": 1,
        "updated_at": "2025-07-28T19:47:46Z"
    },
    "status": 200,
    "success": true,
    "timestamp": "2025-07-28T20:40:58Z"
}

In case of an error:

{
    "error": "Invalid token",
    "status": 401,
    "success": false,
    "timestamp": "2025-07-28T20:41:54Z"
}