🚀 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.

giswater-api version	Supported Giswater DB versions
0.1 – 0.7	4.0 – 4.7
0.8	4.8+

🚀 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

Endpoint	Method	Description
/	GET	Root endpoint (version info)
/health	GET	Health check (DB connection status)

Basic Module

Endpoint	Method	Description
/basic/getfeaturechanges	GET	Fetch GIS features modified since specified date
/basic/getinfofromcoordinates	GET	Fetch GIS features info from coordinates
/basic/getfeaturesfrompolygon	GET	Fetch GIS features inside a polygon
/basic/getselectors	GET	Fetch current selectors
/basic/getsearch	GET	Search features
/basic/getarcauditvalues	GET	Fetch arc audit values
/basic/getlist	GET	Generic list query with paging and filters

CRM Module

Endpoint	Method	Description
/crm/hydrometers	POST	Insert hydrometers (single or bulk)
/crm/hydrometers/{code}	PATCH	Update single hydrometer by code
/crm/hydrometers	PATCH	Update multiple hydrometers in bulk
/crm/hydrometers/{code}	DELETE	Delete single hydrometer by code
/crm/hydrometers	DELETE	Delete multiple hydrometers in bulk
/crm/hydrometers	PUT	Replace all hydrometers (full sync mode)

OM - Mincut

Endpoint	Method	Description
/om/mincuts	GET	List mincuts
/om/mincuts/{mincut_id}	GET	Get mincut dialog data
/om/mincuts	POST	Create a new mincut
/om/mincuts/{mincut_id}	PATCH	Update an existing mincut
/om/mincuts/{mincut_id}	DELETE	Delete a mincut
/om/mincuts/{mincut_id}/valves	GET	List valves associated to a mincut
/om/mincuts/{mincut_id}/valves/{valve_id}/toggle-unaccess	POST	Toggle valve unaccess status and recalculate mincut
/om/mincuts/{mincut_id}/valves/{valve_id}/toggle-status	POST	Update valve status in a mincut
/om/mincuts/{mincut_id}/start	POST	Start mincut and interrupt supply
/om/mincuts/{mincut_id}/end	POST	End mincut and restore supply
/om/mincuts/{mincut_id}/cancel	POST	Cancel mincut and keep issue recorded

OM - Profile

Endpoint	Method	Description
/om/profiles	POST	Create a new profile

OM - Flow

Endpoint	Method	Description
/om/flow	POST	Calculate upstream/downstream flow trace

OM - District Metered Areas

Endpoint	Method	Description
/om/dmas	GET	Returns collection of DMAs
/om/macrodmas	GET	Returns collection of macro DMAs
/om/dmas/{dma_id}/hydrometers	GET	Retrieve DMA hydrometers data with location, status, and measurements
/om/dmas/{dma_id}/parameters	GET	Retrieves DMA parameters for performance analysis
/om/dmas/{dma_id}/flowmeters	GET	Retrieve DMA flowmeters data with location, status, and flow
/om/dmas/{dma_id}/connecs	GET	Retrieve DMA connecs data from ve_connec

OM - Mapzones

Endpoint	Method	Description
/om/macrosectors	GET	Returns collection of macrosectors
/om/sectors	GET	Returns collection of sectors
/om/presszones	GET	Returns collection of presszones
/om/macrodqas	GET	Returns collection of macro DQAs
/om/dqas	GET	Returns collection of DQAs
/om/macroomzones	GET	Returns collection of macro OM zones
/om/omzones	GET	Returns collection of OM zones
/om/omunits	GET	Returns collection of OM units

OM - Routing

Endpoint	Method	Description
/routing/getobjectoptimalpathorder	GET	Get optimal path through network points using Valhalla routing engine
/routing/getobjectparameterorder	GET	Get features ordered by parameter

---

📂 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.