riftbound-api 0.6.0

REST API for Riftbound catalogue, collections, decks, validation, and analysis.

riftbound-api

API REST FastAPI pour consulter les données Riftbound, gérer des collections et des decks, puis orchestrer la validation et l'analyse via riftbound-core et riftbound-database.

Version actuelle : 0.6.0 (pré-1.0, persistance PostgreSQL collection/decks).

Installation

Prérequis : Python 3.12 ou 3.13.

python -m pip install riftbound-api

Avec le driver PostgreSQL recommandé en production :

python -m pip install "riftbound-api[postgres]"

Développement local :

python -m pip install -e ".[dev]"

Démarrage rapide

export RIFTBOUND_DATABASE_URL="postgresql+psycopg://user:password@localhost:5432/riftbound"
uvicorn riftbound_api.main:app --host 0.0.0.0 --port 8000

Sans base configurée, les routes catalogue, collection et decks renvoient 503 DATABASE_UNAVAILABLE.

Documentation interactive : GET /docs et GET /openapi.json.

Configuration

Variable	Obligatoire	Défaut	Rôle
RIFTBOUND_DATABASE_URL	Oui (prod)	—	URL PostgreSQL (postgresql+psycopg://…)
RIFTBOUND_API_ENV	Non	development	Environnement
RIFTBOUND_API_LOG_LEVEL	Non	INFO	Niveau de log JSON
RIFTBOUND_API_CORS_ORIGINS	Non	vide	Origines CORS autorisées
RIFTBOUND_API_AUTH_MODE	Non	disabled	disabled, api_key ou oidc (réservé)
RIFTBOUND_API_DEV_USER_ID	Non	dev-user	Utilisateur injecté en mode disabled
RIFTBOUND_API_API_KEYS	Non	vide	Clés API key:user_id ou JSON

Les secrets ne sont jamais loggés. Chaque réponse d'erreur inclut un request_id (X-Request-Id).

Endpoints principaux

Domaine	Exemples
Système	GET /health, GET /version
Catalogue	GET /cards, GET /cards/{card_id}
Références	GET /sets, GET /rules/current, GET /keywords, GET /formats
Collection	GET /collections/me, POST /collections/me/cards
Decks	GET /decks, POST /decks, POST /decks/{id}/validate, POST /decks/{id}/analyze
Import/export	POST /decks/import, POST /decks/{id}/export
Validation inline	POST /deck-validation

Spécification complète : docs/.

Migrations base de données

Les migrations sont fournies par riftbound-database :

python -m pip install riftbound-database
riftbound-db upgrade

Tests d'intégration PostgreSQL

Prérequis locaux : Docker.

Les tests marqués postgresql démarrent automatiquement un conteneur éphémère (docker compose, projet riftbound-api-pytest) puis l'arrêtent et le suppriment à la fin de la session pytest.

python -m pytest -m postgresql -q

Pour réutiliser une base déjà disponible (CI ou instance locale) :

export RIFTBOUND_TEST_POSTGRESQL_URL="postgresql+psycopg://postgres:postgres@localhost:5432/riftbound_test"
python -m pytest -m postgresql -q

Pour un PostgreSQL manuel persistant (hors pytest) :

docker compose up -d

Limitations connues (0.6.0)

• Authentification OIDC : RIFTBOUND_API_AUTH_MODE=oidc est réservé et rejeté au démarrage.
• Snapshots de validation API : repository mémoire process (non persistés PostgreSQL).
• Snapshots d'analyse deck : non implémentés côté API.

Frontière de persistance

riftbound-api dépend de riftbound-database pour le provider, les sessions, les repositories catalogue, les transactions et les migrations. baobab-database reste encapsulé et n'est jamais utilisé directement par l'API.

SQLAlchemy est déclaré uniquement pour classifier ses exceptions publiques lors du mapping HTTP. L'API ne définit aucun modèle, repository, moteur ou migration SQLAlchemy propre.

Qualité

python -m ruff check .
python -m mypy src tests
python -m coverage run -m pytest -m "not integration and not postgresql" -q
python -m coverage report --fail-under=85

Licence

MIT — voir LICENSE.