semapform_api/API_SERVICE.md

Signature Validation API Service

This is a lightweight Python service that provides signature validation for the PHP application.

Why a separate service?

The bibapi library is Python-only and provides access to your library catalog. Rather than rewriting this in PHP, we keep a small Python service running just for signature validation.

Running the Service

Option 1: Direct Python

python api_service.py

Option 2: With uvicorn

uvicorn api_service:app --host 0.0.0.0 --port 8001

Option 3: Docker (if you can run containers internally)

FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY api_service.py .
EXPOSE 8001
CMD ["uvicorn", "api_service:app", "--host", "0.0.0.0", "--port", "8001"]

docker build -t signature-api .
docker run -d -p 8001:8001 signature-api

Configuration

Set the API endpoint in your PHP config. Update php/config.php:

// Signature validation API endpoint (optional)
define('SIGNATURE_API_URL', getenv('SIGNATURE_API_URL') ?: 'http://localhost:8001');

Testing

# Health check
curl http://localhost:8001/health

# Validate a signature
curl "http://localhost:8001/api/validate-signature?signature=ABC123"

Production Deployment

1. Same server: Run on a different port (8001) alongside your PHP application
2. Separate server: Run on internal network, update SIGNATURE_API_URL in PHP config
3. Systemd service (Linux):

Create /etc/systemd/system/signature-api.service:

[Unit]
Description=Signature Validation API
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/signature-api
Environment="PATH=/var/www/signature-api/.venv/bin"
ExecStart=/var/www/signature-api/.venv/bin/uvicorn api_service:app --host 0.0.0.0 --port 8001
Restart=always

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl enable signature-api
sudo systemctl start signature-api

Security

• In production, update CORS allow_origins to only your PHP server domain
• Consider adding API key authentication if exposed to public network
• Run behind reverse proxy (nginx/Apache) with SSL

Notes

• The service is stateless and lightweight
• No data persistence required
• Can be scaled horizontally if needed
• Falls back gracefully if unavailable (ELSA form fields just won't have validation hints)