Generic API

A flexible Express.js API with versioning and API key authentication.

Features

• ✅ API key authentication (query parameter or header)
• ✅ Versioning support (v1, v2)
• ✅ Route-specific or global API keys
• ✅ Redis Streams integration
• ✅ Comprehensive error handling
• ✅ Built-in documentation endpoint
• ✅ Test script included

Installation

npm install

Configuration

Copy .env.example to .env and configure:

API_PORT=3000
API_KEY=8aPVt9BtYxC1GavZIALY
API_KEY_ALERTS=your-alerts-key-here
API_KEY_TEST=your-test-key-here
API_KEY_LEDTEXT=your-ledtext-key-here

REDIS_STREAM_HOST=192.168.2.14
REDIS_STREAM_PORT=6379

Usage

Start the API

npm start

Or with nodemon for development:

npm run dev

Run Tests

npm test

Authentication

API key can be provided in two ways:

1. Query parameter: ?key=YOUR_API_KEY
2. Header: X-API-Key: YOUR_API_KEY

Example:

curl "http://localhost:3000/v1/test?key=8aPVt9BtYxC1GavZIALY"

Or:

curl -H "X-API-Key: 8aPVt9BtYxC1GavZIALY" http://localhost:3000/v1/test

Endpoints

Root

• GET / - API information

Documentation

• GET /docs - Complete API documentation

Test

• GET /v1/test - Test connectivity and authentication
• POST /v1/test - Test POST with data

Alerts

• GET /v1/alerts - List available alert services
• POST /v1/alerts/:service - Send alert from service

LED Text

• GET /v1/ledtext - LED Text route health and endpoint list
• POST /v1/ledtext/display - Display custom text on the LED panel
• POST /v1/ledtext/warn - Display warning text with preset color/animation
• POST /v1/ledtext/error - Display error text with preset color/animation
• POST /v1/ledtext/info - Display info text with preset color/animation
• POST /v1/ledtext/clear - Clear the LED display

Alert POST Body

{
  "message": "Alert message (required)",
  "level": "info|warn|error (optional, default: info)",
  "data": {
    "any": "additional data"
  }
}

Examples

Send an alert from Lidarr

curl -X POST "http://localhost:3000/v1/alerts/lidarr?key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Album download completed",
    "level": "info",
    "data": {
      "artist": "Test Artist",
      "album": "Test Album"
    }
  }'

Send an alert from Radarr

curl -X POST "https://api.loener.nl/v1/alerts/radarr?key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Movie download failed",
    "level": "error"
  }'

Display custom LED text

curl -X POST "http://localhost:3000/v1/ledtext/display?key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello LED",
    "color": "00ff00",
    "animation": 1
  }'

Display warning text on the LED

curl -X POST "http://localhost:3000/v1/ledtext/warn?key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Temperature high"
  }'

Versioning

The API supports versioning. Default version is v1:

• /v1/alerts/:service - Version 1 (current)
• /v2/alerts/:service - Version 2 (not implemented)
• /alerts/:service - Defaults to v1
• /v1/ledtext/* - Version 1 LED display endpoints
• /ledtext/* - Defaults to v1 LED display endpoints

Route-Specific API Keys

You can configure different API keys for different routes:

API_KEY=global-key-here          # Used as fallback
API_KEY_ALERTS=alerts-only-key   # Only for /alerts routes
API_KEY_TEST=test-only-key       # Only for /test routes
API_KEY_LEDTEXT=ledtext-only-key # Only for /ledtext routes

If a route-specific key is not set, it falls back to the global API_KEY.

Error Responses

All errors return JSON:

{
  "success": false,
  "error": "Error message",
  "timestamp": "2026-01-03T10:00:00.000Z"
}

Error Codes

• 401 - Missing API key
• 403 - Invalid API key
• 404 - Endpoint not found
• 400 - Bad request (e.g., missing required field)
• 500 - Internal server error
• 501 - Not implemented (e.g., v2 routes)

Integration with Redis Streams

Alerts are published to Redis Stream alerts for processing by the StreamConsumer service.

Development

File structure:

api/
├── index.js              # Main server file
├── routes/
│   ├── alerts.js         # Alerts route handler
│   ├── ledtext.js        # LED text route handler
│   └── test.js           # Test route handler
├── test-api.js           # Test script
├── package.json
├── .env.example
└── README.md

License

ISC