Aller au contenu principal

Familles de routes

Ikawaari expose actuellement plusieurs familles d’API déjà implémentées, avec une harmonisation progressive vers une structure plus uniforme.

Cette page explique comment lire correctement la surface API de la plateforme, et quelle forme doit désormais être considérée comme canonique.

Pourquoi les familles de routes comptent​

Différentes capacités sont exposées à travers différents groupes de routes, selon que l’appelant est :

  • une intégration server-to-server utilisant des clés API
  • un dashboard marchand authentifié ou un client marchand
  • une checkout session ou un flux de checkout hébergé
  • une intégration spécifique à un module comme escrow, billing ou marketplace

Familles de routes cœur​

Ressources publiques ou orientées clé API​

La forme canonique pour les API publiques versionnées est désormais :

  • api/v1/<resource>

Les ressources publiques doivent utiliser des noms pluriels, RESTful, en kebab-case. Exemples :

  • api/v1/payment-intents
  • api/v1/webhook-endpoints
  • api/v1/payouts
  • api/v1/balance
  • api/v1/balance-transactions

Sur le périmètre public déjà harmonisé, les anciennes routes dupliquées ont été retirées pour éviter toute confusion. Les nouvelles intégrations, SDK et exemples doivent utiliser exclusivement ces routes canoniques.

Familles de routes dashboard et compte marchand​

Certaines capacités utilisées par le dashboard marchand existent sous des familles authentifiées dédiées. Elles sont documentées dans les guides dashboard lorsque l’usage est pertinent pour les marchands, mais elles ne doivent pas être traitées comme des endpoints d’intégration serveur publics.

La plateforme expose également une famille analytique dédiée :

  • api/v1/intelligence/*

Cette famille porte les lectures trust, lifecycle, recommendations, decisions et la matérialisation de snapshots, avec compatibilité temporaire maintenue côté merchant/reporting.

Familles de routes checkout​

Les fonctionnalités liées au checkout sont réparties entre une API publique versionnée et une surface publique hébergée non encore totalement normalisée :

  • api/v1/checkout/sessions
  • api/checkout/*

La direction cible est :

  • création et gestion de ressources publiques via api/v1/...
  • endpoints purement liés au runtime de checkout hébergé migrés progressivement vers une structure cohérente documentée

Familles de routes produit et module​

Les domaines implémentés ont aussi des groupes de routes dédiés, notamment :

  • api/v1/escrow/*
  • api/v1/billing/*
  • api/v1/marketplace/*
  • api/v1/payout-engine/*
  • api/v1/funding/*

Endpoints système​

Les endpoints système ne sont pas des endpoints d’intégration publique. Ils incluent notamment :

  • santé et disponibilité
  • métriques
  • callbacks fournisseurs
  • webhooks système

Pour cette catégorie, la stabilité de l’URL prime sur la version applicative.

Règle de conception canonique​

À partir de maintenant, la règle cible est :

  • API publiques : api/v{version}/resource
  • API dashboard/compte marchand : routes authentifiées documentées uniquement lorsqu’elles correspondent à un usage marchand public
  • API système : non versionnées

Les nouvelles ressources doivent éviter :

  • les racines sans namespace
  • les noms au singulier pour des collections
  • le snake_case dans les segments d’URL
  • les mélanges v1/resource, /resource, api/resource pour une même capacité

Règle de documentation​

La documentation Ikawaari doit documenter en priorité la forme canonique recommandée. Les alias de compatibilité ne doivent être mentionnés que s’ils sont réellement encore actifs sur le périmètre concerné.

L’objectif est d’être exact d’abord, puis d’améliorer progressivement la cohérence, la gouvernance et la couverture de référence générée dans le temps.

Pages liées​