En bref
L'approche "design-first" signifie que votre spécification d'API est rédigée avant votre code d'implémentation – et que cette spécification dirige tout ce qui suit : maquettes, documentation, tests et stubs client. Choisir une plateforme qui supporte ce workflow de bout en bout élimine le frottement constant lié à la synchronisation du code et de la documentation. Cet article explique l'approche "design-first" et évalue les caractéristiques d'un bon outillage, en présentant Apidog comme une plateforme complète "design-first".
ApidogEssayez Apidog gratuitement
Introduction
La plupart des développeurs apprennent à construire des API en mode "code-first". Vous écrivez une route, ajoutez quelques annotations, exécutez un générateur et obtenez de la documentation. Cela fonctionne. Jusqu'à ce que ça ne fonctionne plus.
La documentation dérive. Les annotations deviennent obsolètes. Un nouvel ingénieur modifie le format de réponse mais oublie de mettre à jour le décorateur. Six mois plus tard, la documentation indique que l'API renvoie un tableau de chaînes de caractères, et la réponse réelle renvoie un tableau d'objets avec un champ value.
Le "design-first" inverse cette approche. La spécification est la source de vérité. Le code, la documentation et les maquettes sont tous dérivés de celle-ci. Lorsque la spécification change, tout change en même temps – car tout a été généré à partir d'elle.
Ce n'est pas une distinction théorique. Les équipes qui adoptent le "design-first" signalent moins de surprises d'intégration, un développement frontend plus rapide (car les maquettes sont disponibles dès le premier jour) et une documentation précise car elle n'a jamais été un artefact secondaire.
Mais le "design-first" nécessite un outillage qui rend la rédaction de la spécification suffisamment rapide pour être pratique. Si la définition d'un point de terminaison dans votre outil de spécification prend 20 minutes et que l'écriture du gestionnaire de route prend 5 minutes, personne n'utilisera l'outil de spécification. La plateforme doit rendre le "design-first" plus rapide que le "code-first", pas plus lent.
Ce que le "design-first" signifie en pratique
Le "design-first" est un workflow, pas une technologie. Voici à quoi il ressemble à chaque étape du développement d'API :
Avant d'écrire du code
La conception de l'API est définie comme une spécification OpenAPI. Cela inclut :
- Tous les chemins d'accès aux points de terminaison et les méthodes HTTP
- Définitions des paramètres de requête (chemin, requête, en-tête)
- Schémas de corps de requête pour les points de terminaison POST/PUT/PATCH
- Schémas de réponse pour tous les codes de statut (200, 400, 401, 422, 500)
- Exigences d'authentification
- Descriptions de champs et exemples
Cette revue de conception est l'endroit où la plupart des décisions importantes sont prises : nommage, structures de données, modèles de gestion des erreurs.
Pendant le développement
La spécification est publiée sur un serveur de maquettes. Les ingénieurs frontend construisent à partir de la maquette. Les ingénieurs backend implémentent selon la spécification, la traitant comme leur document d'exigences. Les deux équipes travaillent en parallèle sans se bloquer mutuellement.
Après l'implémentation
Des tests automatisés valident que l'implémentation réelle correspond à la spécification. Toute déviation du contrat fait échouer le test.
Lorsque les exigences changent
La spécification est mise à jour en premier. Les deux équipes examinent le changement. Les maquettes se mettent à jour automatiquement. Les tests signalent toute implémentation qui ne respecte pas la spécification mise à jour.
Ce dont une plateforme "design-first" a besoin
Tous les outils API ne supportent pas les workflows "design-first". Voici ce qui distingue les outils qui le font de ceux qui ne le font pas.
Éditeur d'API visuel
Le YAML brut est un mauvais support de conception. Un éditeur visuel vous permet de vous concentrer sur la structure et la sémantique de l'API sans vous battre avec l'indentation YAML. L'éditeur doit générer un OpenAPI valide, supporter la réutilisation de schémas (composants) et valider en temps réel.
Validation OpenAPI
La spécification doit être un OpenAPI valide avant d'être utilisée pour quoi que ce soit. La validation en ligne détecte les erreurs pendant l'édition plutôt qu'au moment de la génération de code ou de la maquette.
Génération automatique de maquettes à partir de la spécification
Écrivez la spécification, obtenez une maquette. Aucune étape supplémentaire. La maquette doit renvoyer des données qui respectent les types de champs, les formats et les contraintes du schéma. C'est ce qui rend le développement parallèle pratique.
Aperçu de la documentation avec des exemples réalistes
La spécification doit être rendue sous forme de documentation lisible que vous pouvez partager avec les parties prenantes pendant la phase de conception. Les membres de l'équipe non techniques devraient pouvoir la lire et donner leur avis.
Workflow de révision d'équipe
Le "design-first" traite les changements de spécification comme des changements de code : quelqu'un propose un changement, d'autres le révisent, il est approuvé ou révisé. La plateforme a besoin d'un système de commentaires asynchrones et de suivi des changements.
Exportation vers OpenAPI standard
La spécification doit être portable. Vous devez pouvoir l'exporter vers un OpenAPI standard et l'utiliser avec n'importe quel outil en aval : générateurs de code, passerelles API, frameworks de test.
Apidog en tant que plateforme "design-first"
L'architecture d'Apidog est construite autour de la spécification comme artefact principal. L'onglet de conception, le serveur de maquettes, le moteur de tests et la documentation sont tous connectés à la même définition d'API sous-jacente.
Éditeur OpenAPI visuel
L'interface de conception d'Apidog utilise l'édition basée sur des formulaires. Chaque point de terminaison est un formulaire structuré : chemin, méthode, paramètres, corps de requête, réponses. Les champs de schéma sont définis avec un sélecteur de type, un éditeur de description, des règles de validation et une annotation de maquette.
Vous n'avez pas besoin d'écrire du YAML, sauf si vous le souhaitez. Apidog fournit une vue brute qui affiche la représentation YAML ou JSON de la spécification et vous permet de l'éditer directement si vous préférez. Les modifications dans la vue visuelle se synchronisent avec la vue brute et vice versa.
Les composants de schéma sont de première classe. Définissez un schéma UserProfile dans la section des composants. Référencez-le avec $ref dans n'importe quel point de terminaison. Modifiez le schéma une fois, et chaque point de terminaison qui le référence reflète le changement.
Prévisualisation de la documentation en temps réel
Lorsque vous concevez un point de terminaison, la vue de la documentation se met à jour en temps réel. Vous pouvez prévisualiser comment le point de terminaison apparaîtra dans la documentation publiée sans quitter l'interface de conception. La prévisualisation affiche les descriptions rendues, les tableaux de schémas avec les types de champs et les contraintes, et les exemples de réponses.
Partagez un lien de documentation avec les chefs de produit ou les responsables frontend pendant la phase de conception pour examen. Ils n'ont rien à installer.
Maquette intelligente : de la spécification à la maquette fonctionnelle
Lorsque vous enregistrez un nouveau point de terminaison dans le concepteur d'Apidog, le serveur de maquettes est immédiatement prêt. L'URL de la maquette apparaît dans l'interface. La maquette génère des données de réponse basées sur vos schémas :
- Les champs de chaîne avec
format: emailrenvoient des adresses e-mail valides - Les champs entiers avec
minimumetmaximumrenvoient des valeurs dans la plage - Les champs d'énumération renvoient des valeurs d'énumération sélectionnées aléatoirement
- Les objets et tableaux imbriqués suivent la structure du schéma imbriqué
- Les composants
$refsont résolus et simulés correctement
Vous pouvez également définir des règles de maquette personnalisées pour des scénarios spécifiques : renvoyer un 404 lorsque le paramètre de chemin est 0, ou renvoyer une charge utile spécifique pour une valeur de paramètre de requête spécifique.
Révision d'équipe et suivi des changements
Les changements de spécification d'API dans Apidog sont visibles par tous les membres de l'espace de travail. Des commentaires peuvent être ajoutés à des points de terminaison ou des champs spécifiques. L'historique des changements suit qui a changé quoi et quand.
Pour les workflows "design-first", cela signifie que les changements de spécification passent par la même culture de révision que les changements de code, sans nécessiter d'outil ou de processus séparé.
Design-first vs. Code-first : les véritables compromis
Le "design-first" n'est pas universellement supérieur. Voici une comparaison honnête.
Avantages du "design-first" :
- Le frontend et le backend peuvent travailler en parallèle (gain de vitesse majeur)
- La documentation est précise car elle est la source, non un dérivé
- Les problèmes d'intégration apparaissent tôt, pendant la revue de conception, et non tard, pendant l'intégration
- Les contrats d'API sont explicites et vérifiables
- Les changements d'API passent par un processus de revue par défaut
Inconvénients du "design-first" :
- Temps initial pour définir la spécification avant d'écrire du code
- Les outils de spécification ont une courbe d'apprentissage
- Nécessite de la discipline pour maintenir l'implémentation synchronisée avec la spécification
- Une spécification trop détaillée tôt peut vous enfermer dans des décisions avant de comprendre le domaine
Avantages du "code-first" :
- Développement initial plus rapide pour les petits projets expérimentaux
- Moins de processus pour les développeurs solo qui itèrent rapidement
- Pas d'outil de spécification à apprendre
Inconvénients du "code-first" :
- La documentation est toujours un artefact secondaire et tend à dériver
- Le frontend doit attendre le backend avant que le travail d'intégration puisse commencer
- Le contrat est implicite, rendant les changements disruptifs plus difficiles à détecter
- La refactorisation des API nécessite des mises à jour manuelles de la documentation
Pour les équipes avec plus d'un ingénieur travaillant sur une API, le "design-first" donne généralement de meilleurs résultats. La discipline de la spécification d'abord est particulièrement rentable pour les fonctionnalités nécessitant une coordination significative entre le frontend et le backend.
Outils supportant les workflows "design-first"
Apidog
Plateforme "design-first" complète : éditeur visuel, maquettes instantanées, documentation, tests et révision d'équipe dans un seul outil. La version gratuite couvre l'ensemble des fonctionnalités. La puissante génération de maquettes est un véritable élément différenciateur.
Stoplight Studio
Meilleur éditeur OpenAPI de sa catégorie avec l'outil de linting Spectral pour l'application des styles. Pas de serveur de maquettes intégré ni de moteur de tests. Idéal pour les organisations qui ont besoin d'outils de gouvernance. Coûteux pour les petites équipes.
SwaggerHub
Plateforme mature d'édition et de collaboration OpenAPI. Largement utilisée en entreprise. Capacités de maquette limitées. Pas de tests. Bon pour les organisations axées sur les spécifications déjà dans l'écosystème Swagger.
Postman (avec API Builder)
Postman dispose d'un onglet de conception d'API qui génère des spécifications OpenAPI, mais les workflows de conception et de collection semblent déconnectés. Le serveur de maquettes nécessite une configuration manuelle à partir de collections plutôt qu'une auto-génération à partir des spécifications. Convient aux équipes "code-first" qui souhaitent des outils de documentation.
Insomnia (avec mode document)
Insomnia prend en charge l'édition de spécifications OpenAPI et fournit une maquette de base. Moins raffiné que les outils dédiés au "design-first". Bon pour les développeurs solo qui veulent une option légère.
Mettre en place un workflow "design-first" dans Apidog
Étape 1 : Commencez par la spécification, pas par une collectionCréez un nouveau projet et ouvrez l'onglet de conception. Résistez à l'envie de commencer par le constructeur de requêtes. Définissez au moins le chemin du point de terminaison, la méthode et le schéma de réponse avant d'envoyer une seule requête.
Étape 2 : Définissez d'abord les composants partagésAvant d'ajouter des points de terminaison, définissez les schémas qui seront réutilisés : format de réponse d'erreur, enveloppe de pagination, champs d'entité communs. Cela évite les incohérences ultérieures.
Étape 3 : Obtenez l'URL de la maquette tôtCopiez l'URL de la maquette dès que le point de terminaison est enregistré. Partagez-la avec l'ingénieur frontend. Ils peuvent commencer à construire avec elle immédiatement.
Étape 4 : Révisez la documentation avant d'écrire du codePrévisualisez la documentation générée. Si une description de champ n'est pas claire dans la documentation, elle ne le sera pour personne qui lira le code. Corrigez-la dans la spécification.
Étape 5 : Verrouillez la spécification avant de commencer l'implémentationUne fois la revue de conception terminée et les commentaires résolus, traitez la spécification comme verrouillée pour ce sprint. Les changements d'implémentation qui nécessitent des mises à jour de spécification doivent passer par un processus de revue, et non être effectués silencieusement.
Étape 6 : Exécutez des tests de validation de schéma en CIConfigurez la suite de tests d'Apidog pour valider les schémas de réponse à chaque exécution de CI. C'est la garde-fou automatisée qui maintient l'implémentation et la spécification synchronisées.
FAQ
Le "design-first" est-il uniquement pour les API REST ?Non. Le principe "design-first" s'applique à tout protocole où vous pouvez définir un contrat : GraphQL schema-first, gRPC avec protobuf, AsyncAPI pour les systèmes événementiels. Apidog supporte la conception REST et GraphQL. Pour gRPC, les fichiers proto servent le même objectif de contrat d'abord.
Devons-nous définir chaque point de terminaison avant de commencer le développement ?Non. Vous pouvez adopter le "design-first" au niveau des fonctionnalités : définissez la spécification pour la fonctionnalité que vous êtes sur le point de construire avant d'écrire du code, même si d'autres parties de la codebase sont "code-first". L'adoption incrémentale fonctionne.
Comment le "design-first" fonctionne-t-il avec les sprints agiles ?Les sessions de conception au début du sprint définissent le contrat API pour les fonctionnalités de ce sprint. Le frontend et le backend travaillent en parallèle pendant le sprint. La revue de spécification devient une partie de la planification du sprint.
Que se passe-t-il si l'implémentation doit s'écarter de la spécification originale ?Cela arrive. Le bon processus consiste à mettre à jour la spécification en premier, obtenir l'accord des parties prenantes (en particulier le frontend), puis mettre à jour l'implémentation. Cela maintient la spécification comme source de vérité plutôt que l'implémentation.
Pouvons-nous générer des stubs de serveur à partir de l'exportation OpenAPI d'Apidog ?Oui. Exportez la spécification d'Apidog en OpenAPI 3.x, puis utilisez n'importe quel générateur de code standard pour créer des stubs de serveur. openapi-generator prend en charge plus de 50 langages et frameworks de serveur.
Comment gérer le versionnement des spécifications ?Apidog maintient l'historique des changements au sein d'un projet. Pour les changements de version majeurs qui sont maintenus en parallèle (v1 et v2 toutes deux actives), des projets ou des branches séparés fonctionnent bien.
Le "design-first" demande un petit investissement initial en discipline et rapporte considérablement en réduisant les coûts d'intégration. La plateforme que vous choisissez devrait rendre cet investissement initial aussi faible que possible. Si la rédaction de la spécification est pénible, les équipes l'ignoreront. L'éditeur visuel d'Apidog, la maquette instantanée et la prévisualisation de la documentation font du "design-first" le chemin de la moindre résistance plutôt que le chemin de la plus grande vertu.