Conventions de l'API

L’API centrale est le seul point d’entrée de l’application mobile. Elle sert le même catalogue, sur la même base, que le site et le back-office.

Contrat et référence interactive

Le contrat est un fichier OpenAPI 3.1 versionné avec le code (docs/api/openapi.yaml). Un test automatique compare ses routes à celles de l’application dans les deux sens : une route sans contrat, ou un contrat sans route, fait échouer la suite. Le client TypeScript du mobile en sera généré, jamais écrit à la main.

Une référence interactive (Scalar) est servie par l’application à l’adresse /docs/api, avec un panneau « essayer » et des extraits de code par langage.

Conventions

Sujet	Règle
Adresse	/api/v1/… — la version est dans l’adresse.
Format	JSON, en entrée comme en sortie. Envoyer Accept: application/json.
Erreurs	{ "message": "…" } ; en 422, { "message": "…", "errors": { "champ": ["…"] } }.
Codes	200 lecture, 201 création, 202 accepté (envoi du code), 401 connexion requise, 403 refus, 404 introuvable ou non publié, 409 média indisponible, 422 données refusées, 429 trop de requêtes.
Authentification	Authorization: Bearer <jeton> — un jeton par appareil, obtenu par la connexion par code.
Langue	Accept-Language: ar ou fr pour les messages ; français par défaut. Le contenu est en arabe quelle que soit la langue.
Identifiants	Les produits et domaines sont adressés par leur identifiant d’URL (slug), les contenus par leur numéro.
Montants	En centimes, avec la devise et un libellé prêt à afficher.
Dates	ISO 8601 avec fuseau.

Limites de fréquence

Route	Limite
Toute l’API	120 requêtes par minute, par compte ou par adresse.
Demande de code	5 par minute et par adresse ; 3 par 10 minutes et par identifiant.
Vérification du code	10 par minute, par identifiant et adresse.

Une limite atteinte répond 429 avec un message.

Routes

Méthode	Route	Accès	Page
GET	/catalogue	public	Catalogue
GET	/catalogue/themes, /catalogue/themes/{slug}	public	Catalogue
GET	/catalogue/products/{slug}	public	Catalogue
GET	/contents/{id}/stream	extrait : public · verrouillé : jeton et droit	Lecture
POST	/auth/otp/request	public, limité	Comptes
POST	/auth/otp/verify	public, limité	Comptes
GET	/me	jeton	Comptes
POST	/auth/logout	jeton	Comptes