bgeoopengis/giswater-api repository overview

⁠🚀 Giswater FastAPI Service

Versions
CI
Status
Meta

A lightweight, modular FastAPI application with Swagger UI, Docker support, Keycloak authentication, and Gunicorn + Uvicorn for production.

⁠📚 Table of Contents

• Overview⁠
• Compatibility⁠
• Quick Start⁠
• Configuration⁠
• Authentication⁠
• Plugins⁠
• Running with Docker⁠
• Deployment (Gunicorn + Uvicorn)⁠
• API Endpoints⁠
• Project Structure⁠
• Testing & Linting⁠
• Releasing⁠
• License⁠

⁠✨ Overview

Giswater API exposes a clean HTTP surface to query and operate a Giswater database. It wraps existing GIS and network operations behind FastAPI endpoints, so desktop tools, mobile apps, and integrations can run the same workflows without directly touching the database.

How it works

• Each route validates input with Pydantic models, builds a standard payload, and calls Postgres procedures in the Giswater schema.
• Modules are toggled via environment variables, so you only expose the domains you need (Basic, OM, CRM, Routing, Water Balance).
• Optional Keycloak authentication protects routes while keeping Swagger/OpenAPI usable.

Why it is useful

• Centralizes complex GIS/business logic behind stable HTTP endpoints.
• Supports automated workflows (field operations, routing) without QGIS client coupling.
• Keeps API surface modular and controllable per deployment.

How to use it

• Base path: /api/v1 (Swagger docs at /api/v1/docs).
• Enable/disable modules in .env (API_* toggles).
• Use REST endpoints directly or via the autogenerated OpenAPI client.

⁠🔄 Compatibility

This service is versioned alongside the Giswater database. Use matching ranges to avoid subtle schema/API mismatches.

⁠🚀 Quick Start

⁠1️⃣ Clone the Repository

git clone https://github.com/Giswater/giswater-api.git
cd giswater-api

⁠2️⃣ Set Up Virtual Environment

python3 -m venv venv
source venv/bin/activate  # for Windows PowerShell: .\venv\Scripts\activate
pip install -e ".[dev]"

⁠3️⃣ Run Locally

uvicorn app.main:app --reload

📌 API Docs available at: http://127.0.0.1:8000/api/v1/docs⁠

⁠⚙️ Configuration

Copy the env template and customize:

cp .env.example .env

⁠Environment Variables

API toggles (enable/disable modules):

API_BASIC=true
API_PROFILE=true
API_MINCUT=true
API_MAPZONES=true
API_ROUTING=true
API_CRM=true

Database:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=giswater_db
DB_USER=postgres
DB_PASSWORD=postgres
DB_SCHEMA=ws
# DATABASE_URL=postgresql://user:pass@host:5432/dbname

Keycloak (optional):

KEYCLOAK_ENABLED=false
KEYCLOAK_URL=https://keycloak.example.com
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=giswater-api
KEYCLOAK_CLIENT_SECRET=your-secret
KEYCLOAK_ADMIN_CLIENT_SECRET=your-admin-secret
KEYCLOAK_CALLBACK_URI=http://localhost:8000/callback

⁠🔐 Authentication

Keycloak integration is optional. When enabled:

• All endpoints require a valid JWT token
• Swagger UI shows "Authorize" button for OAuth2 flow
• User info available in routes via get_current_user() dependency

When disabled, endpoints are public and return an anonymous user context.

⁠🔌 Plugins

Custom plugins can extend the API. Place plugin folders in plugins/:

plugins/
└── my-plugin/
    └── ...

Plugins are auto-loaded at startup. See example plugin⁠.

⁠🐳 Running with Docker

⁠Build the Image

docker build -t giswater-api .

⁠Run the Container

docker run -d -p 8000:8000 giswater-api

⁠With Env File

docker run -d -p 8000:8000 \
  --env-file .env \
  -v /var/log/giswater-api:/app/logs \
  giswater-api

⁠Environment Variables

Set the variables listed in the Configuration section (or via --env-file).

⁠🏗️ Deployment (Gunicorn + Uvicorn)

For production, run:

gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app.main:app

⁠🛠️ API Endpoints

⁠Root & Health

⁠Basic Module

⁠CRM Module

⁠OM - Mincut

⁠OM - Profile

⁠OM - Flow

⁠OM - District Metered Areas

⁠OM - Mapzones

⁠OM - Routing

⁠📂 Project Structure

giswater-api/
│── app/
│   │── .env.example         # Environment variable template
│   │
│   │── models/              # Pydantic models (organized by module)
│   │   │── basic/           # Basic module models
│   │   │── crm/             # CRM module models
│   │   │── om/              # OM (mincut, dma, mapzones) models
│   │   │── routing/         # Routing module models
│   │   └── util_models.py   # Shared utility models
│   │
│   │── routers/             # API endpoints (organized by module)
│   │   │── basic/           # GIS feature queries
│   │   │── crm/             # Hydrometer CRUD
│   │   │── om/              # OM operations (mincut, profile, flow, dma, mapzones)
│   │   │── routing/         # Optimal path routing
│   │
│   │── utils/               # Utilities and helpers
│   │   │── utils.py         # General utilities
│   │   └── routing_utils.py # Valhalla routing helpers
│   │
│   │── config.py            # Configuration loader
│   │── database.py          # Database connection manager
│   │── dependencies.py      # FastAPI dependencies
│   │── keycloak.py          # Keycloak OAuth2/OIDC integration
│   │── main.py              # FastAPI app entry point
│   └── static/              # Static files (favicon, etc.)
│
│── plugins/             # Plugin directory (see plugins/readme.md)
│── tests/               # Unit and integration tests
│── .github/workflows/   # CI/CD (flake8 lint, pytest)
│── Dockerfile           # Docker build config
│── gunicorn.conf.py     # Gunicorn production config
│── pyproject.toml       # Project metadata, dependencies, and tooling config
│── scripts/
│   │── release.sh       # Release script (bash)
│   └── release.ps1      # Release script (PowerShell)
└── README.md

⁠✅ Testing & Linting

⁠Run Tests

pytest

⁠Run Linter

ruff check .

CI/CD runs both on push via GitHub Actions (.github/workflows/).

⁠🚀 Releasing

1. Update CHANGELOG.md with the new version's changes and commit.
2. Run the release script:

# Bash
./scripts/release.sh 0.8.0

# PowerShell
.\scripts\release.ps1 0.8.0

The script will:

• Abort if there are uncommitted changes
• Update the version in pyproject.toml
• Commit, tag vX.Y.Z, create branch release/X.Y
• Push everything to origin

⁠📌 License

This project is free software, licensed under the GNU General Public License (GPL) version 3 or later. Refer to the LICENSE⁠ file for details.