Réponse.

Historiquement, la description des interfaces entre systèmes était le domaine des architectes et des intégrateurs, souvent réduite à des échanges d'email avec des structures de données. À l'ère de SOA et plus encore dans une architecture microservices, le rôle de l'analyste système dans la formalisation et le soutien des contrats d'intégration a considérablement augmenté.

Problème

Une description erronée, incomplète ou obsolète des interfaces API devient la cause : d'incompatibilité des services, d'une augmentation du nombre de bugs, de l'impossibilité d'effectuer des changements sans perturber l'ensemble du système. Dans des projets multiservices, le nombre de points d'intégration atteint des dizaines et des centaines.

Solution

L'analyste système applique des pratiques modernes :

formalisation des contrats à travers des outils comme OpenAPI/Swagger pour REST, protocoles gRPC, WSDL/XSD pour SOAP ;
description de scénarios typiques d'appel et de situations d'erreur ;
développement de schémas d'événements (modèle orienté événement) pour l'échange en temps réel ;
maintien d'une documentation à jour et génération automatique des contrats ;
validation des changements avec les propriétaires de tous les services concernés.

Un élément clé est le maintien d'une version correcte et de la traçabilité des changements des contrats, ainsi que l'intégration des cas de test pour la validation des interactions.

Caractéristiques clés :

Utilisation de normes exploitables par machine (OpenAPI/YAML).
Prise en compte de tous les scénarios d'utilisation et d'erreur.
Communication régulée entre les équipes de services différents.

Questions pièges.

L'analyste doit-il recueillir les exigences de l'API uniquement auprès du client et des développeurs internes ?

Non, il est important d'impliquer toutes les équipes intégrées, de prendre en compte les exigences des partenaires externes pour éviter des lacunes ou des incompatibilités.

Peut-on documenter l'API seulement au stade de remise du système ?

Non, la spécification de l'API est formulée et convenue avant la réalisation, sinon la rétrocompatibilité sera compromise à chaque étape.

La spécification OpenAPI est-elle suffisante comme documentation pour tous les cas d'échange ?

Non, OpenAPI décrit les structures, mais les scénarios d'interaction (par exemple, l'ordre d'appel, la séquence des événements, les erreurs business) doivent être détaillés par l'analyste dans la documentation utilisateur.

Erreurs typiques et anti-patterns

Fournir un doc obsolète ou une description "humaine" au lieu de la spécification.
Ne pas décrire le traitement des erreurs, des scénarios implicites.
Absence de contrôle de version et de traçabilité des changements.

Exemple de la vie réelle

Cas négatif : Le système de logistique s'est intégré avec des transporteurs externes. Le contrat a été décrit uniquement "en mots". Après la sortie des modifications, des refus d'intégration massifs ont eu lieu, des retards.

Avantages :

Coûts de travail minimaux au départ.

Inconvénients :

Pannes massives.
Retouches urgentes.
Réputation négative.

Cas positif : L'analyste a créé un OpenAPI avec des exemples d'erreurs/scénarios réussis, a convenu de la version, a recueilli des retours d'expérience de toutes les équipes.