Présentation de l'API REST

Sovrium expose une API REST sur les tables, enregistrements, vues, activité, analytique et authentification. Chaque point de terminaison accepte et renvoie du JSON, applique le RBAC avec des permissions par champ, et émet une unique enveloppe d'erreur canonique.

La liste complète des chemins vit dans la Référence des points de terminaison ; cette page en est le contrat.

URL de base

Tous les points de terminaison sont relatifs à l'URL de base de votre instance Sovrium.

http://localhost:3000/api

Authentification et contrôle d'accès

L'authentification repose sur les sessions (Better Auth). Les requêtes touchant des ressources protégées doivent porter l'une des deux formes d'identifiant, et il n'y en a pas d'autre :

L'accès est régi par des rôles plus des permissions par champ. Les permissions de table acceptent all, authenticated, ou une liste arbitraire de noms de rôles — admin, member et viewer sont donc les valeurs intégrées par défaut, pas un ensemble figé. Une application sans bloc auth évalue les requêtes sous un rôle guest.

Conformément à la politique anti-énumération, une requête authentifiée qui n'a pas accès à une ressource renvoie 404, jamais 403, afin que l'appelant ne puisse distinguer « introuvable » de « accès refusé ».

Contrat de réponse d'erreur

Toutes les réponses 4xx/5xx emploient une unique enveloppe JSON canonique : un seul décodeur couvre donc toutes les erreurs.

{
  "success": false,
  "message": "Authentication required",
  "code": "UNAUTHORIZED"
}

code provient d'une énumération stable de treize valeurs : UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, BAD_REQUEST, CONFLICT, PAYLOAD_TOO_LARGE, RATE_LIMITED, INTERNAL_ERROR, SERVICE_UNAVAILABLE, STORAGE_ERROR, DATABASE_ERROR, QUOTA_EXCEEDED. Un error optionnel (identifiant de type hérité) et un details (tableau de chaînes) peuvent également être présents.

Lorsque l'échec porte sur des champs, un tableau errors[] nomme chaque champ fautif :

{
  "success": false,
  "message": "One or more fields failed validation",
  "code": "VALIDATION_ERROR",
  "errors": [{ "field": "id", "message": "Cannot write to readonly field 'id'" }]
}

Une création d'enregistrement refusée par la base de données alimente ce même tableau. Lorsqu'une contrainte CHECK, de clé étrangère ou NOT NULL rejette une valeur sur POST /api/tables/:table/records, la réponse nomme la colonne sur laquelle la contrainte est déclarée :

{
  "success": false,
  "message": "A submitted value is not allowed by this resource",
  "code": "VALIDATION_ERROR",
  "field": "status",
  "errors": [{ "field": "status", "message": "A submitted value is not allowed by this resource" }]
}

Seul un champ que vous avez réellement envoyé est nommé, et la réponse n'énumère jamais les valeurs acceptées par un champ. La colonne est retrouvée à partir de la contrainte déclenchée et n'est rapportée que si elle correspond à une clé de votre charge utile : une réponse d'erreur ne peut donc jamais servir à découvrir un schéma que vous ne pouvez pas lire par ailleurs. Si aucune clé envoyée ne correspond, field et errors[] sont omis et le message de la classe répond seul.

Cette attribution se limite à ce chemin de création unitaire. Un PATCH, ou une écriture en lot refusée par la même contrainte, répond avec un statut et un code identiques, le message de la classe et sans field.

Les dépassements de taille de lot se répartissent sur deux codes : dépasser le maximum par opération (1000 en création, 100 en mise à jour, 100 identifiants en suppression, 100 en upsert) est un 400 VALIDATION_ERROR, tandis qu'une charge utile au-delà de la garde dure de 1000 identifiants donne 413.

La forme de la requête ne change jamais son code. Une collision d'unicité répond 409, qu'elle survienne dans une écriture unique ou dans un lot : un seul gestionnaire couvre les deux cas. Les autres classes de contrainte (check, clé étrangère, NOT NULL) répondent 400 VALIDATION_ERROR sur tous les chemins, car celles-là rejettent la valeur envoyée au lieu d'entrer en conflit avec une ligne déjà existante.

La configuration est uniquement du code

Il n'existe aucune API d'édition de schéma à l'exécution. Sovrium est un interpréteur de configuration-as-code : vous modifiez une application en éditant son app.ts / app.yaml puis en redéployant — le même fichier que la CLI valide hors ligne avec sovrium validate. Le tableau de bord d'administration reflète les données d'exécution, jamais la configuration (Tableau de bord d'administration) ; les changements de schéma s'appliquent au démarrage suivant (Migrations).

Santé

Déplacé vers Référence des points de terminaison.

Tables

Déplacé vers Référence des points de terminaison.

Enregistrements

Déplacé vers Référence des points de terminaison.

Vues

Déplacé vers Référence des points de terminaison.

Activité

Déplacé vers Référence des points de terminaison.

Analytique

Déplacé vers Référence des points de terminaison.

Endpoints d'authentification

Déplacé vers Référence des points de terminaison.

Fonctionnalités transversales

• Pagination — les points de terminaison de liste paginent leurs résultats (limit + offset).
• Suppressions douces — DELETE met à la corbeille par défaut ; ?permanent=true et ?purge=true suppriment définitivement sur la même route.
• RBAC — chaque route protégée est filtrée par rôle, avec guest pour les applications sans authentification.
• Permissions par champ — contrôle fin lecture/écriture par champ et par rôle.
• Limitation de débit — les points de terminaison d'authentification et d'administration sont limités.
• Enveloppe d'erreur canonique — chaque 4xx/5xx partage la forme ci-dessus.

Pages associées

• Référence des points de terminaison — chaque chemin, méthode et description.
• OpenAPI — le document lisible par machine et /api/scalar.
• Présentation des enregistrements — le modèle de données derrière les routes d'enregistrements.
• Clés API — l'identifiant x-api-key et comment un utilisateur en crée un.
• Permissions de table — RBAC et accès par champ.
• Durcissement de la sécurité — déployer cette surface en toute sécurité.