Documentation · API Reference

Référence API.

Base URL : https://<ton-projet>.zeroapi.app. Toutes les réponses sont en JSON, encodées en UTF-8, avec en-tête Content-Type: application/json.

Le code généré inclut une route /openapi.json et un Swagger UI sur /docs. Ce qui suit est la base commune ; ton schéma spécifique est servi par ton backend déployé.

Authentification

Toutes les routes protégées attendent un header :

Authorization: Bearer <access_token>

Authentification

Tous les endpoints d'authentification renvoient un access token JWT et un refresh token rotatif. Stocke le refresh token dans un cookie HTTP-only.

POST/auth/register

Crée un nouveau compte avec un email et un mot de passe. Envoie un email de vérification.

Paramètre	Type	Requis	Description
`email`	`string`	oui	Email valide, non déjà utilisé.
`password`	`string`	oui	12 caractères minimum, complexité enforced.
`name`	`string`	—	Nom affiché.

POST/auth/login

Authentifie un utilisateur existant. Renvoie un access token et écrit un cookie de refresh.

Paramètre	Type	Requis	Description
`email`	`string`	oui	Email du compte.
`password`	`string`	oui	Mot de passe en clair, hashé argon2id côté serveur.

POST/auth/refresh

Échange un refresh token contre une nouvelle paire access + refresh.

POST/auth/logout

Révoque le refresh token courant et clear le cookie associé.

Ressources CRUD

Pour chaque entité déclarée dans ton prompt, ZeroAPI génère ces cinq endpoints en respectant le RBAC configuré. Exemple ici sur la ressource users.

GET/users

Liste paginée des utilisateurs. Supporte filtres, tri et pagination cursor.

Paramètre	Type	Requis	Description
`filter[role]`	`string`	—	Filtre par rôle exact (`admin`, `customer`...).
`sort`	`string`	—	Champs séparés par virgule. Préfixe `-` pour DESC.
`limit`	`number`	—	1–100 (défaut : 25).
`cursor`	`string`	—	Curseur opaque renvoyé par la requête précédente.

POST/users

Crée une nouvelle ressource. Body validé par Zod selon le schéma déclaré.

GET/users/:id

Récupère une ressource par son identifiant unique.

PATCH/users/:id

Mise à jour partielle. Les champs absents sont laissés tels quels.

DELETE/users/:id

Soft delete par défaut. Ajoute `?hard=true` pour supprimer définitivement (admin uniquement).

Fichiers et uploads

ZeroAPI génère deux endpoints pour gérer les fichiers via signed URLs vers un bucket S3-compatible (R2, Backblaze, AWS).

POST/files/sign

Demande une URL signée d'upload. Renvoie l'URL et le `key` final.

Paramètre	Type	Requis	Description
`filename`	`string`	oui	Nom original du fichier.
`contentType`	`string`	oui	MIME type validé contre une whitelist.
`size`	`number`	oui	Taille en octets — limite configurable.

POST/files/confirm

Confirme l'upload après PUT côté client. Crée la ligne de métadonnée en base.

Codes d'erreur

Format unifié pour toutes les erreurs :

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "email doit être valide",
    "details": [ … ],
    "requestId": "req_01HABC…"
  }
}

Code	Nom	Description
`400`	`Bad Request`	Validation Zod en échec — voir le tableau `details`.
`401`	`Unauthorized`	Token manquant, invalide ou expiré.
`403`	`Forbidden`	Authentifié mais sans le rôle requis.
`404`	`Not Found`	Ressource inexistante ou hors du tenant courant.
`409`	`Conflict`	Contrainte d'unicité violée.
`422`	`Unprocessable`	Format valide mais sémantique refusée (ex : transition d'état impossible).
`429`	`Too Many Requests`	Rate limit dépassé. Voir headers `RateLimit-*`.
`500`	`Server Error`	Erreur interne. Tracée et notifiée à l'équipe.

Rate limits

Par défaut, 120 requêtes / minute par token authentifié, 60 / minute par IP non-authentifiée. Trois en-têtes sont retournés sur chaque réponse : RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. Modulable par endpoint dans le code généré.