Prévenir les changements : La méthode Contract First pour les APIs

Intro

Imaginez que vous construisez un pont entre deux rives, et qu'au milieu de la construction, les plans pour l'une des rives changent sans préavis. Les ajustements et les retards non planifiés s'accumulent rapidement.

Ce scénario se produit souvent dans le développement de logiciels lorsqu'un contrat d'API change sans que l'équipe en soit informée. Avec l'approche « Contract First », ce problème est considérablement réduit.

Dans cet article, nous explorerons les divers avantages que cette méthodologie offre et quand l'appliquer.

Qu'est-ce que le Contract First ?

La méthodologie Contract First est une approche de développement d'API qui consiste à définir les contrats de service avant de commencer l'implémentation. Cela permet de renforcer la communication avec votre équipe et les parties prenantes et de définir ensemble la bonne API qui répond à différentes exigences.

Ces contrats peuvent être implémentés en utilisant différents outils tels que OpenAPI ou WSDL pour décrire l'interface, les types de données et divers usages afin de partager vos réflexions et d'exposer avec vos coéquipiers la vision future ou l'évolution de l'API. De plus, ces outils vous permettent de traduire le contrat en code, par exemple, OpenAPI permet la génération des objets dont vous avez besoin pour l'API, vous aidant ainsi à éviter les goulots d'étranglement de codage.

Voici un exemple de configuration pour transformer un contrat Swagger en objet via Maven :

<build>
	<plugins>
		<plugin>
	    <groupId>org.openapitools</groupId>
	    <artifactId>openapi-generator-maven-plugin</artifactId>
	    <version>7.14.0</version>
	    <executions>
	        <execution>
	            <goals>
	                <goal>generate</goal>
	            </goals>
	            <configuration>
	                <inputSpec>[your_path_directory/swagger.json]</inputSpec>
	                <generatorName>java</generatorName>
	                <modelPackage>com.example</modelPackage>
	            </configuration>
	        </execution>
	    </executions>
		</plugin>
	</plugins>
</build>

Et avec cette commande mvn generate-sources , Cela crée des objets dans le dépôt cible à l'emplacement indiqué dans <modelPackage> :

target/generated-sources/
└── com
		└── example
				└── model
						├── Model1.java
						├── Model2.java
						└── ...

Cycle de vie

Le processus implique plusieurs étapes clés pour obtenir un contrat bien défini et validé. Voici les étapes clés du Contract First :

1. Collecte des exigences : Comme pour toutes les fonctionnalités ou évolutions, les exigences fonctionnelles et non fonctionnelles doivent être collectées et décrites pour comprendre les usages de l'API et ses contraintes techniques.
2. Définition du contrat : Spécifiez les différentes interactions avec l'API, telles que les endpoints et les données, avant d'écrire la première ligne de code. Cette étape nécessite plus d'interaction avec les membres de l'équipe et les différentes parties prenantes qui utiliseront la future API.
3. Validation du contrat : Le contrat doit être validé par les pairs et les différentes parties prenantes pour s'assurer que l'API répond aux exigences.
4. Tests basés sur le contrat : Le contrat est validé, nous pouvons donc écrire les tests basés sur celui-ci pour garantir que le développement futur corresponde aux exigences de l'entreprise et du contrat d'API.
5. Développement parallèle : permet à différentes équipes de commencer le développement simultanément. Par exemple, l'équipe backend peut implémenter une future fonctionnalité, tandis que l'équipe frontend peut simultanément implémenter le futur appel à l'endpoint sans attendre que l'API soit déployée en production.
6. Déploiement : Déployez l'API dans un environnement de staging pour des tests et une validation supplémentaires. Une fois validée, déployez-la dans l'environnement de production.
7. Retour et améliorations : Après avoir déployé votre API en production, le processus n'est pas terminé. Il est important de recueillir les retours des parties prenantes et d'utiliser ces retours pour apporter des améliorations à l'API.

Pourquoi utiliser le Contract First ?

Comme nous pouvons le voir, l'élément crucial de cette approche est la communication. En effet, elle nous oblige à comprendre comment notre API sera utilisée par les parties prenantes.

Un autre avantage est qu'elle vous encourage à documenter votre processus de réflexion et à le partager avant de le transformer en code. Cela garantit la validation avec vos pairs et aide à éviter les modifications de l'API après le codage ou, pire encore, avoir à retravailler de grandes portions de code.

De plus, avec des outils comme OpenAPI, vous pouvez facilement transformer votre contrat en code. Diverses méthodes existent pour convertir votre contrat en code, vous permettant d'économiser un temps significatif en n'ayant pas à écrire manuellement le code pour les endpoints ou les structures de données. Il ne reste plus qu'à implémenter la logique métier et écrire les tests.

En résumé, les principaux avantages sont les principes suivants :

• Vérifier l'interopérabilité : Assurer que différents systèmes peuvent fonctionner ensemble de manière transparente.
• Collaborer avec les collègues : Discuter des évolutions futures ou de la création d'APIs avec votre équipe.
• Définir la feuille de route pour votre API : Planifier et esquisser le chemin de développement futur de votre API.
• Fournir l'API future aux parties prenantes : Partager les détails de l'API à venir avec les développeurs front-end, back-end ou d'autres utilisateurs.
• Implémentation facile en code : Utiliser des outils comme OpenAPI pour une génération de code simple.

L'approche Contract First est-elle toujours utile ?

L'approche Contract First est bénéfique, mais elle n'est pas toujours utile dans certains cas.

Par exemple, si votre projet est une preuve de concept (POC) ou un prototype, votre objectif principal est de démontrer rapidement sa valeur. Dans de tels cas, passer du temps à créer un contrat extensif et précis peut ne pas être nécessaire, car le Contract First peut ne pas ajouter de valeur significative et pourrait entraîner une perte de temps.

De plus, pour les petits projets, tels que des scripts simples, le Contract First peut ne pas être essentiel. De même, pour les projets internes au sein de votre propre équipe, en particulier ceux impliquant des microservices, le Contract First peut ne pas être nécessaire. Cela est dû au fait que les membres de votre équipe sont à la fois les parties prenantes et les consommateurs, ce qui simplifie la communication et réduit le besoin de contrats formels.

La clé du Contract First est une communication efficace avec les différentes parties prenantes. Si vous déterminez que votre projet ne sera pas utilisé par d'autres, ou s'il s'agit d'un projet expérimental ou trop petit pour appliquer ces principes, alors la mise en œuvre d'un Contract First peut ne pas être nécessaire.

N'oubliez pas qu'un outil doit être utilisé ou non, en fonction du contexte du projet.

Quoi retenir ?

Comme nous l'avons vu tout au long de cet article, la méthodologie Contract First facilite la collaboration sur les changements de contrat d'API avec diverses parties prenantes. Cette approche est particulièrement bénéfique lorsque votre API est utilisée par plusieurs parties prenantes, car elle assure un alignement entre votre équipe et les consommateurs.

Un avantage significatif de cette approche est le temps économisé. En convenant du contrat dès le départ, vous pouvez éviter de nombreuses révisions après le codage. De plus, transformer le contrat en code simplifie le processus de développement, permettant aux développeurs de se concentrer sur la mise en œuvre de la logique métier et l'écriture des tests.

Pour ces raisons, je vous recommande vivement d'essayer cette méthode dans vos projets pour améliorer la communication, réduire le temps de développement et assurer un processus de développement d'API plus robuste.

Bon codage 😊