API — Introduction
Philosophie
Patrimo est une application Next.js App Router full-stack. Il n'y a pas de backend séparé : la logique serveur est exposée via deux mécanismes complémentaires.
Server Actions (API principale)
Les Server Actions ("use server") constituent l'immense majorité de l'interface serveur. Ce sont des fonctions TypeScript appelées directement depuis les Server Components et Client Components Next.js, sans couche HTTP intermédiaire.
Avantages dans ce contexte :
- Types partagés end-to-end (TypeScript natif, pas de contrat OpenAPI à maintenir)
- Pas de round-trip HTTP supplémentaire pour les mutations
- Revalidation de cache (
revalidatePath) intégrée - Auth vérifiée à chaque appel via
auth()— pas de middleware séparé
Endpoints REST (minimaux)
Deux routes HTTP existent pour les besoins d'infrastructure :
| Route | Usage |
|---|---|
/api/auth/* | NextAuth v5 — signin, signout, session, CSRF |
/api/health | Healthcheck Docker / Coolify |
Ces routes ne font pas partie de l'API applicative — elles ne sont pas appelées par le code UI.
Conventions communes
Authentification
Toute Server Action commence par :
const userId = await requireUserId();
// → lève "Non authentifié" si pas de session JWT valide
Toute tentative d'accéder à une ressource d'un autre utilisateur retourne une erreur "<Ressource> introuvable" (pas de 403 — pas de leak d'existence).
Format de retour
Les actions de mutation retournent un discriminated union :
type ActionResult = { success: true } | { success: false; error: string }
type UpsertResult = { success: true; id: string } | { success: false; error: string }
Les actions de lecture retournent directement la donnée (ou null/undefined si introuvable).
Revalidation
Après toute mutation, les chemins concernés sont revalidés via revalidatePath("/route"). Pas de cache stale côté client.