Irrigation REST API - Setup Guide

Installation on Debian Bookworm (12)

1. Install Dependencies

# Update package list
sudo apt update

# Install Python 3 and pip
sudo apt install python3 python3-pip python3-venv openssl -y

# Create a virtual environment (recommended)
python3 -m venv /opt/garden/irrigation-api-env
source /opt/garden/irrigation-api-env/bin/activate

# Install Flask
pip install flask

2. Generate Self-Signed SSL Certificate

mkdir /opt/garden/irrigation-api
cd /opt/garden/irrigation-api

# Generate certificate (valid for 1 year)
openssl req -x509 -newkey rsa:4096 -nodes \
  -out server.crt -keyout server.key -days 365 \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

# Set proper permissions
chmod 600 server.key
chmod 644 server.crt

3. Set API Token

# Set a strong API token (change this!)
export IRRIGATION_API_TOKEN="your-secure-random-token-here"

# To make it persistent, add to ~/.bashrc or create a .env file
# Ensure this is in the "pi" user
echo 'export IRRIGATION_API_TOKEN="your-secure-random-token-here"' >> ~/.bashrc

4. File Structure

Ensure your directory looks like this:

irrigation-api/
├── irrigation_api.py    # The API server
├── irrigation.py        # Your existing irrigation script
├── server.crt          # SSL certificate
└── server.key          # SSL private key

5. Make Scripts Executable

chmod +x irrigation-api.py
chmod +x irrigation.py

6. Run the API Server

# Make sure you're in the virtual environment
source /opt/garden/irrigation-api-env/bin/activate

# Export the token if not in .bashrc
export IRRIGATION_API_TOKEN="your-secure-random-token-here"

# Run the server
python3 irrigation-api.py

API Usage

Authentication

All requests (except /health) require a bearer token in the Authorization header:

Authorization: Bearer your-secure-random-token-here

Endpoints

Health Check (No Auth Required)

curl -k https://localhost:5000/health

Response:

{"status": "ok", "service": "irrigation-api"}

Control Irrigation (Auth Required)

curl -k -X POST https://localhost:5000/irrigation \
  -H "Authorization: Bearer your-secure-random-token-here" \
  -H "Content-Type: application/json" \
  -d '{"relay": "farbed", "action": "on"}'

Valid Values

Relays: farbed, nearbed, mag, plants, valve5, pump1, pump2, all

Actions: on, off, status

Example Requests

Turn on a relay:

curl -k -X POST https://localhost:5000/irrigation \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"relay": "pump1", "action": "on"}'

Check status:

curl -k -X POST https://localhost:5000/irrigation \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"relay": "all", "action": "status"}'

Turn off all relays:

curl -k -X POST https://localhost:5000/irrigation \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"relay": "all", "action": "off"}'

Running as a System Service

To run the API server automatically on boot:

1. Create systemd service file

sudo nano /etc/systemd/system/irrigation-api.service

2. Add the following content:

[Unit]
Description=Irrigation REST API Server
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/opt/garden/irrigation-api
Environment="IRRIGATION_API_TOKEN=your-secure-random-token-here"
ExecStart=/opt/garden/irrigation-api-env/bin/python3 /opt/garden/irrigation-api/irrigation-api.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

3. Enable and start the service

sudo systemctl daemon-reload
sudo systemctl enable irrigation-api
sudo systemctl start irrigation-api
sudo systemctl status irrigation-api

Security Notes

1. Change the default token - Use a strong, random token
2. Firewall - Restrict access to port 5000 to trusted IPs only:

   sudo ufw allow from TRUSTED_IP to any port 5000

3. Self-signed certificate - The -k flag in curl bypasses certificate validation. For production, consider using Let's Encrypt
4. HTTPS only - Never expose this API over plain HTTP

Troubleshooting

Check logs:

sudo journalctl -u irrigation-api -f

Test irrigation.py directly:

./irrigation.py -r farbed -a status

Check if port is listening:

sudo netstat -tulpn | grep 5000