9

Rest API

seriousm4x edited this page 2025-05-22 09:03:04 +02:00

Table of Contents

• Authentication
• Some basic endpoints you might find useful:
• I've extended the default PocketBase API:
• Example bash script to wake device, run rsync and shutdown the device:

This project is based on PocketBase, therefore you can use their API. You can check our the documentation here: https://pocketbase.io/docs/api-records/

To get better documentation than this wiki page: login to the admin dashboard at localhost:8090/_/ and click the "API Preview" button at the top right. You should get plenty examples on all things you can do. There is also filtering and much more.

Authentication

All routes require the "Authorization" header with jwt token. You can get the jwt token like this:

Users:

• [POST] /api/collections/users/auth-with-password

Superusers:

• [POST] /api/collections/_superusers/auth-with-password

With body:

{
  "identity": "username or email",
  "password": "password"
}

Some basic endpoints you might find useful:

• [GET] /api/collections/devices/records returns first 30 devices
• [GET] /api/collections/devices/records/:id returns single device by id
• [PATCH] /api/collections/devices/records/:id updates single device with json body
• [DELETE] /api/collections/devices/records/:id deletes single device by id

I've extended the default PocketBase API:

• [GET] /api/upsnap/wake/:id wakes the device with given id
• [GET] /api/upsnap/wakegroup/:id wakes the whole device group with given id
• [GET] /api/upsnap/sleep/:id send device with given id to sleep using sleep-on-lan
• [GET] /api/upsnap/reboot/:id wakes the device with given id
• [GET] /api/upsnap/shutdown/:id shuts down the device with given id
• [GET] /api/upsnap/scan scans the network for devices

Example bash script to wake device, run rsync and shutdown the device:

#!/bin/bash

# Configurations
UPSNAP_URL="http://localhost"
UPSNAP_USER="YOUR_EMAIL"
UPSNAP_PASSWORD="YOUR_PASSWORD"
UPSNAP_DEVICE_ID="YOUR_DEVICE_ID"
TIMEOUT=120

# Get authentication token
AUTH_TOKEN=$(curl -s -X POST "$UPSNAP_URL/api/collections/_superusers/auth-with-password" \
    -H "Content-Type: application/json" \
    -d "{\"identity\": \"$UPSNAP_USER\", \"password\": \"$UPSNAP_PASSWORD\"}" | jq -r '.token')

if [[ -z "$AUTH_TOKEN" ]]; then
    echo "Auth token is empty. Failed to authenticate. Exiting."
    exit 1
fi

echo "Authentication successful. Token acquired."

# Wake up the device
curl -s "$UPSNAP_URL/api/upsnap/wake/$UPSNAP_DEVICE_ID" \
    -H "Authorization: Bearer $AUTH_TOKEN"

echo "Wake request sent. Waiting $TIMEOUT seconds for the device to come online..."

# Wait until the device is online
START_TIME=$(date +%s)
while true; do
    STATUS=$(curl -s "$UPSNAP_URL/api/collections/devices/records/$UPSNAP_DEVICE_ID" \
        -H "Authorization: Bearer $AUTH_TOKEN" | jq -r '.status')

    if [[ "$STATUS" == "online" ]]; then
        echo "Device is online!"
        break
    fi

    CURRENT_TIME=$(date +%s)
    ELAPSED_TIME=$((CURRENT_TIME - START_TIME))
    if [[ $ELAPSED_TIME -ge $TIMEOUT ]]; then
        echo "Timeout reached. Device did not come online. Exiting."
        exit 1
    fi

    sleep 1
done

# Perform rsync
rsync -avz --progress src/ target/

# Shutdown the device
curl -s "$UPSNAP_URL/api/upsnap/shutdown/$UPSNAP_DEVICE_ID" \
    -H "Authorization: Bearer $AUTH_TOKEN"

echo "Shutdown request sent."