Aller au contenu

Quickstart API

Créer un service, ajouter explicitement FastAPI, puis exposer un cas d'usage.

init ne crée aucun transport. add-adapter installe l'extra arclith[fastapi] et le blueprint FastAPI complet uniquement lorsque l'API est choisie.

Prérequis

  • Python 3.13 ;
  • uv.

Installer d'abord arclith-cli comme outil global géré par uv, puis vérifier que la commande est disponible :

Bash
1
2
uv tool install arclith-cli
arclith-cli version

Étapes

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
arclith-cli init todo-api --dir .
cd todo-api
arclith-cli add-entity Todo
arclith-cli add-usecase CreateTodo --entity Todo
arclith-cli add-adapter --capability repository --adapter memory --yes
arclith-cli add-adapter --capability api --adapter fastapi \
  --param port=8765 --param reload=false --yes
arclith-cli expose-usecase create-todo --via fastapi --feature todos \
  --path /v1/todos --method POST --status-code 201
uv sync

Le service est déjà fonctionnel avec les seuls champs techniques de Entity : CreateTodoUseCase construit l'entité, la persiste via Repository[Todo] et la composition générée l'injecte dans le binding. Ajouter ensuite les mêmes champs métier validés à Todo et CreateTodoCommand. Une composition plus riche qu'un repository unique doit rester explicite dans l'infrastructure.

Lancer l'API :

Bash
1
MODE=api uv run python main.py

Le main.py généré fournit l'API à Uvicorn sous forme de factory importable. Le réglage reload de config/adapters/inbound/fastapi.yaml reste ainsi effectif en développement, sans importer FastAPI avant l'ajout explicite de l'adapter.

Dans un second terminal :

Bash
1
2
3
curl -fsS http://127.0.0.1:8765/openapi.json
curl -fsS -X POST http://127.0.0.1:8765/v1/todos \
  -H 'content-type: application/json' -d '{}'

Résultat

  • Swagger UI s'ouvre sur http://127.0.0.1:8765/docs.
  • OpenAPI contient exactement une opération POST /v1/todos.
  • La création retourne 201 avec uuid, dates d'audit, version et is_deleted, même sans champ métier supplémentaire.

Variante CRUD Complète

Pour exposer le cycle complet plutôt qu'un seul use case :

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
arclith-cli init todo-api
cd todo-api
arclith-cli add-entity Todo --profile minimal
# Déclarer ici les champs métier de Todo, puis figer le contrat CRUD.
arclith-cli add-blueprint crud --entity Todo
arclith-cli add-adapter --capability api --adapter fastapi \
  --param port=8765 --yes
arclith-cli expose-feature todo --via fastapi --path /v1/todos
uv sync
MODE=api uv run python main.py

OpenAPI contient alors les cinq opérations CRUD. Les réponses de création, mise à jour et suppression restent typées (201, 200, 200) ; les erreurs d'item absent et de version obsolète sont déclarées en 404 et 409. L'adapter FastAPI doit précéder la projection et aucun repository durable n'est choisi implicitement. Les schémas de requête reprennent les champs métier et leurs contraintes Pydantic tels qu'ils existaient au moment de add-blueprint ; POST respecte les champs requis et PATCH autorise leur omission sans accepter une valeur invalide.

Erreur Fréquente

Si l'API ne répond pas, vérifier que le port choisi est libre et que config/adapters/inbound/fastapi.yaml contient le même port. Les endpoints de probe ne sont présents qu'après ajout explicite de la capability probe.

Média

Média à produire

Capture : Swagger UI ouvert. Vidéo : création du projet puis appel /health.

Suite

Lire MCP, puis api/fastapi. Pour exporter les traces et métriques sans modifier le service, suivre OpenTelemetry de bout en bout.