La conception API-first est une façon de construire un logiciel où l'équipe commence par l'API, c'est-à-dire le contrat qui décrit les données et les actions que le produit propose, avant de construire le moindre écran. Le site, l'application mobile, l'interface d'administration et les outils des partenaires reposent ensuite sur ce même contrat.

Le sujet concerne les fondateurs qui font développer un produit, les marques qui confient un projet sur mesure à une agence et toute personne qui choisit une plateforme en pensant la connecter à d'autres outils plus tard. Le terme revient souvent dans les devis et les présentations commerciales. Cette page vous aide à comprendre ce qu'il apporte et ce qu'il coûte.

Qu'est-ce que la conception API-first ?

Dans un projet classique, l'équipe dessine les écrans, les développe, puis ajoute une API le jour où quelqu'un demande une application mobile ou une intégration. L'API hérite alors des besoins du site, avec des trous et des noms bizarres.

L'approche API-first inverse l'ordre. L'équipe commence par écrire chaque ressource que le produit manipule (produits, commandes, clients, leçons), chaque action possible sur ces ressources, les champs, les erreurs et les droits d'accès. Cette description se relit comme un plan d'architecte. Une fois validée, les développeurs construisent le serveur qui la respecte et les interfaces qui l'utilisent. Le contrat prend en général la forme d'un document OpenAPI pour une API REST, ou d'un schéma pour une API GraphQL.

Un peu de vocabulaire autour de l'idée :

  • Contrat : la description validée de l'API, source unique de vérité.
  • Design-first : souvent employé comme synonyme. Le contrat est rédigé à la main avant le code.
  • Code-first : l'inverse. On code d'abord et la documentation est générée à partir du code.
  • Serveur de maquette (mock) : une fausse API générée depuis le contrat, qui permet de commencer le front avant que le vrai serveur existe.
  • Headless : un système dont le back-office n'est accessible que par une API, sans interface intégrée. L'API-first mène souvent au headless, mais ce n'est pas la même chose.

API-first ne veut pas dire « nous avons une API ». Beaucoup de produits ont une API ajoutée après coup. API-first signifie que l'API est la colonne vertébrale du produit et que chaque interface officielle l'utilise aussi. Ce n'est pas non plus une technologie : on peut travailler en API-first avec n'importe quel langage ou framework.

Pourquoi c'est important

Le gain de l'API-first, c'est la réutilisation. Vous concevez les règles une fois et chaque canal les partage.

Imaginez une marque de soins qui paie 30 000 € à une agence pour une boutique en ligne sur mesure. Dix-huit mois plus tard, elle veut une application mobile et un portail de vente en gros pour 40 revendeurs. Si la boutique a été construite en partant des écrans, la logique des prix, du stock et des remises vit dans les pages web. L'agence doit l'extraire dans une API avant de pouvoir faire l'application, et chiffre ce travail à 12 000 € en plus de l'application elle-même. Si la boutique a été construite en API-first, cette API existe déjà et elle est documentée. L'application et le portail s'y branchent, et la marque économise l'essentiel de ces 12 000 € et plusieurs semaines.

L'API-first limite aussi les malentendus. Quand le contrat est écrit en premier, la fondatrice, le designer et les développeurs relisent le même document. Un champ manquant, comme « message cadeau sur la commande », apparaît le cinquième jour et non à la dixième semaine, quand les écrans sont déjà faits.

Il y a un coût. Concevoir le contrat prend du temps au départ, souvent 10 à 20 % du budget initial, et demande quelqu'un qui sait bien concevoir une API. Pour une petite boutique qui n'aura jamais qu'un seul site, cet effort risque de ne jamais être rentabilisé.

Comment ça marche

Un projet API-first se déroule en général ainsi :

  • Lister les cas d'usage. Écrire ce que chaque utilisateur doit pouvoir faire : un acheteur passe au checkout, une personne de l'équipe rembourse une commande, un partenaire consulte le stock.
  • Modéliser les ressources. Transformer ces cas en objets (commandes, produits, clients) et en actions autorisées sur chacun.
  • Rédiger le contrat. Décrire les endpoints, les champs, les formats, les erreurs et qui peut appeler quoi, souvent dans un fichier OpenAPI.
  • Le relire à plusieurs. La fondatrice vérifie les règles métier, les designers vérifient que les écrans auront les données nécessaires, les développeurs vérifient que c'est réalisable.
  • Générer une maquette. Les développeurs front et mobile travaillent sur une fausse API qui renvoie des données d'exemple, en parallèle de l'équipe back.
  • Construire et tester par rapport au contrat. Des tests automatiques vérifient que le vrai serveur répond exactement comme prévu.
  • Versionner les changements. Quand le contrat doit évoluer, l'équipe publie une nouvelle version au lieu de casser les applications existantes.

Repères et exemples

Là où l'API-first est en général rentable :

  • Plusieurs interfaces sur les mêmes données. Une boutique web, une application mobile et une caisse en magasin qui lisent le même catalogue.
  • Partenaires et revendeurs. Une marque qui laisse 20 revendeurs ou plus consulter le stock et passer commande automatiquement.
  • Produits vendus à des entreprises. Un SaaS dont les clients veulent le relier à leurs propres outils.
  • Grandes équipes. Dès que cinq développeurs ou plus travaillent en parallèle, un contrat écrit évite les allers-retours permanents. C'est un compagnon fréquent des microservices.

Là où c'est en général disproportionné :

  • Une créatrice qui vend une formation et quelques téléchargements depuis sa page lien en bio.
  • Une petite boutique avec un seul site, sans projet d'application ni de partenaires.
  • Un premier prototype construit en deux semaines pour tester la demande.

Ordres de grandeur : sur un développement sur mesure de 20 000 à 60 000 €, comptez 1 à 3 semaines pour concevoir et relire le contrat. Ajouter une API à un produit existant construit à partir des écrans coûte souvent 30 à 50 % du développement initial, ce qui est le meilleur argument pour le faire dès le départ quand vous savez que d'autres canaux arrivent.

Erreurs fréquentes

  • Le faire pour l'étiquette. Payer pour de l'API-first alors que vous n'aurez jamais qu'un site ajoute du coût sans bénéfice.
  • Écrire le contrat sans le métier. Les développeurs seuls oublient souvent des règles comme les quantités minimales de commande ou les exceptions de TVA.
  • Traiter le contrat comme de la paperasse. Si le code s'éloigne du document et que personne ne le met à jour, l'intérêt disparaît.
  • Concevoir autour d'un écran. Une API calquée sur la mise en page actuelle de la page d'accueil se réutilise mal. Pensez objets métier, pas pages.
  • Oublier le versionnage. Modifier une API en production sans nouvelle version casse l'application mobile que vos clients n'ont pas mise à jour.

Bonnes pratiques

  • Décidez en fonction de vos canaux. Si vous prévoyez une deuxième interface ou un accès partenaire dans les 18 mois, l'API-first mérite la discussion. Sinon, restez simple.
  • Demandez à voir le contrat. Une agence qui travaille vraiment en API-first peut vous montrer le fichier OpenAPI ou le schéma et vous l'expliquer en mots simples.
  • Nommez les choses comme votre entreprise. Si votre équipe dit « collection », l'API ne doit pas dire « groupe de catégories ».
  • Incluez erreurs et droits. Un bon contrat dit ce qui se passe en cas de rupture de stock ou quand une personne n'a pas les droits nécessaires.
  • Gardez le contrat avec le code. Il doit vivre dans le même dépôt et évoluer avec le même processus de relecture.
  • Restez propriétaire. Vérifiez dans le contrat avec l'agence que la spécification, le code et la documentation vous appartiennent.

Dans Roctify

Roctify est un SaaS et une plateforme no-code : vous n'avez pas à concevoir d'API pour vendre. La logique que l'API-first cherche à partager entre canaux est déjà partagée dans Roctify grâce à un catalogue unique. Votre page lien en bio et votre boutique en ligne lisent les mêmes produits, variantes, prix, clients et commandes, et le stock se met à jour partout en même temps. Vous obtenez le principal avantage de l'API-first, une seule source de vérité pour plusieurs canaux, sans commander de back-office sur mesure.

Roctify ne propose pas d'API publique aujourd'hui. Si vous gérez une activité plus importante qui doit échanger des données entre Roctify et d'autres systèmes, les intégrations sur mesure se discutent dans le cadre du plan Enterprise.

FAQ

L'API-first, est-ce la même chose que le headless commerce ?

Pas tout à fait. L'API-first décrit la façon dont un produit est conçu, avec l'API comme fondation. Le headless décrit une installation où l'interface est séparée du back-office et ne lui parle que par une API. Un produit API-first facilite le headless, mais vous pouvez très bien l'utiliser avec son interface standard.

L'API-first rend-il un projet plus cher ?

Il ajoute du temps de conception au départ, souvent 1 à 3 semaines sur un développement sur mesure. Il fait économiser de l'argent ensuite si vous ajoutez une application mobile, un portail partenaire ou des intégrations. Si vous n'ajoutez rien de tout cela, le surcoût initial n'est pas rentabilisé.

Comment savoir si une agence travaille vraiment en API-first ?

Demandez le contrat d'API avant le début du développement et demandez comment l'équipe front avance pendant que le back est en construction. Une vraie équipe API-first parlera de spécification écrite, de serveurs de maquette et de tests de contrat. Une réponse floue signifie souvent que l'API arrive en dernier.