mirror of
https://github.com/kaaninchen/Laterna.git
synced 2026-09-17 19:12:48 +00:00
125 lines
3.1 KiB
Markdown
125 lines
3.1 KiB
Markdown
# 🛋️ 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
|
|
|
|
```sh
|
|
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](https://github.com/siestaw/Laterna/blob/main/config.json.example) 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
|
|
|
|
<details><summary>Docs</summary>
|
|
|
|
### 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" }` |
|
|
|
|
> [!INFO]
|
|
> Every specified ID has to be greater than 0
|
|
|
|
---
|
|
|
|
### cURL examples
|
|
|
|
#### Create a new controller
|
|
|
|
```bash
|
|
$ curl -X POST http://your-server.com/api/v1/controllers \
|
|
-H "Authorization: $TOKEN"
|
|
```
|
|
|
|
> [!INFO]
|
|
> Response with the newly assigned ID. The ID will always be the next available one
|
|
|
|
#### Delete a controller
|
|
|
|
```bash
|
|
$ curl -X DELETE localhost:8080/api/v1/controllers \
|
|
-H "Authorization: $TOKEN" \
|
|
-d '{"ID": 1}'
|
|
```
|
|
|
|
#### Get the current color of all controllers
|
|
|
|
```bash
|
|
$ curl -X GET localhost:8080/api/v1/colors/ \
|
|
-H "Authorization: $TOKEN"
|
|
```
|
|
|
|
#### Get the current color of a specific controller
|
|
|
|
```bash
|
|
$ curl -X GET localhost:8080/api/v1/colors/1 \
|
|
-H "Authorization: $TOKEN"
|
|
```
|
|
|
|
#### Set the color of a controller
|
|
|
|
```bash
|
|
$ curl -X PUT localhost:8080/api/v1/colors/1 \
|
|
-H "Authorization:$TOKEN" \
|
|
-d '{"Color": "#C2C342"}'
|
|
```
|
|
|
|
</details>
|