Mohamed Aziz Ben Mahmoud

API/SDK

1. Un peu d’histoire - Les SDKS

Dans les années 90, la plupart des ERP ou des gros logiciels professionnels (Microsoft Office, Autocad,
SolidWorks…) proposaient un SDK et ceux-ci utilisaient souvent les technologies OLE/COM renommé
ActiveX lorsqu’il s’agissait des composants pour les navigateurs. COM a ensuite évolué ensuite vers un
modèle distribué appelé DCOM. Ces technologies propriétaires de Microsoft avaient un énorme avantage :
elles étaient accessibles depuis les Macros Visual Basic en ce qui concerne Microsoft Office, ou l’IDE
complet Microsoft Visual Basic pour les autres, ce qui permettait d’automatiser bon nombre
d’intégrations. Certes, tous les utilisateurs n’avaient pas l’envie ou la capacité de faire du Visual Basic,
mais ils pouvaient aussi utiliser n’importe quel langage qui permettait ces intégrations, tel que Visual C++
ou encore Borland Delphi.

Ces plateformes de développement rapide (RAD) étaient particulièrement efficaces notamment avec
l’inspecteur d’objets où on pouvait manipuler directement les propriétés, s’enregistrer sur des événements
pour bâtir des automatismes avec des IHM simples. On peut considérer que Visual Basic était le "Low
Code" d’hier, c’est-à-dire que le code que l’on produisait était du code de très haut niveau et destiné à
l’intégration sans l’aspect pur métier qui, lui, était encapsulé par les objets exposés via des composants
OLE/COM. Puis le monde du Web est apparu sans patterns d’intégration aussi évolués. Pour pallier ce
manque, certains fournisseurs passaient par des plugins plus ou moins évolués et peu sécurisés.
D’ailleurs, les gros processus industriels nécessitant beaucoup d’intégration ont continué très longtemps
avec des clients lourds communiquant par des protocoles bas niveau tels que TCP/IP.

2. Du besoin d’enrichir les logiciels SaaS

Parler de SDK pour des solutions SaaS peut sembler incongru, puisqu’on utilise un logiciel SaaS pour
éviter de s’embarrasser avec du développement. Pourtant, si vous êtes une DSI utilisatrice, que vous avez
des centaines d’applications SaaS à gérer avec des intégrations fortes et que vous souhaitez des
fonctionnalités d’intégration spécifiques, cela sera très

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -1-
 Mohamed Aziz Ben Mahmoud

difficile pour l’utilisateur d’imposer au fournisseur SaaS de proposer ces développements spécifiques.
Gérer la combinatoire de toutes les intégrations amènerait à un anti-modèle économique du SaaS. Les
applications SaaS, du fait qu’elles consomment l’infrastructure du fournisseur, doivent éviter de prendre de
l’embonpoint et de perdre cette agilité, qui sont les fondamentaux du modèle. Ajouter du code spécifique
pour un client alourdirait le logiciel pour l’ensemble des utilisateurs, puisqu’il est important que l’ensemble
du parc client d’une application SaaS soit sur une même version.

Que reste-t-il alors comme solution pour faire communiquer les applications entre elles ?

Une première solution serait de réaliser cette intégration par des échanges de fichiers, ce qui est le pattern
historique et en général par des traitements asynchrones nocturnes. Dans un contexte SaaS, cela
supposerait d’accéder à des dépôts de type FTPS ou des systèmes de fichiers distribués comme AWS S3
pour une approche plus moderne.

Même si ce type d’intégration entre logiciels est encore très courant, cela pose un problème
d’asynchronisme. En effet, durant ce qu’on appelle la nuit applicative, il n’y a en général qu’une seule
intégration par jour entre deux logiciels. Si plusieurs logiciels étaient impliqués dans un workflow, cela
signifierait que vous ne synchroniseriez l’ensemble des données qu’au bout de quelques jours, ce qui n’est
plus vraiment dans les standards utilisateurs. Dans ce modèle, augmenter la fréquence des
rafraîchissements peut provoquer des problèmes de performances en pleine journée. Enfin, ce modèle
n’est pas absolument compatible avec une application SaaS sur plusieurs fuseaux horaires.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -2-
 Mohamed Aziz Ben Mahmoud

Une autre possibilité serait de faire de l’intégration entre les bases de données. Cela serait une très
mauvaise idée car cela supposerait que vous deviez ouvrir sur Internet les bases de données des
utilisateurs, ce qui est très dangereux. Pour compenser le risque de sécurité, vous pourriez mettre en
place un VPN entre les bases de données, mais cela signifierait aussi que votre infrastructure ne serait
pas très homogène et avec des particularités par client, ce qui nuirait à l’expansion de votre plateforme
SaaS. Cela supposerait également que les autres fournisseurs SaaS ouvrent eux aussi leurs bases de
données, ce que peu d’entre eux feront pour les mêmes raisons de sécurité. Enfin, vous seriez rapidement
bloqué dans vos évolutions futures, puisque vous devriez alors garantir la stabilité du schéma de votre
base de données (si vous êtes en SQL, ce qui reste encore le cas le plus courant).

En effet, le client qui a investi sur du code, même spécifique, ne doit pas être obligé de le revoir à chaque
fois que vous livrez une nouvelle version. En quelque sorte, dans ce modèle, le schéma de base de
données deviendrait une norme d’interfaçage qui pourra difficilement évoluer.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -3-
 Mohamed Aziz Ben Mahmoud

Heureusement, les API ont été inventées sur le Web pour résoudre ce problème. Nous allons voir par la
suite que ce n’est que depuis 2017/2018 qu’on retrouve la même flexibilité sur les API que ce que les SDK
proposaient auparavant.

Voici un schéma d’intégration utilisant des API et un programme spécifique réalisant l’intégration entre un
logiciel de comptabilité et votre logiciel [Link] :

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -4-
 Mohamed Aziz Ben Mahmoud

Commençons par un retour historique sur les API SOAP, qui étaient le standard des années 2000/2010.

3. Les API SOAP

Si vous interrogez les jeunes développeurs, ceux-ci vous diront certainement, sous réserve qu’ils en aient
entendu parler, que le SOAP, c’est "has been" : maintenant, il faut utiliser les interfaces REST ! Il nous
semble pourtant essentiel de comprendre l’approche SOAP et

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -5-
 Mohamed Aziz Ben Mahmoud

d’analyser les vraies raisons de l’abandon de cette technologie. À l’inverse, ce n’est pas en vous lançant
précipitamment dans une stratégie REST que vous résoudrez tous vos problèmes : en effet, sur certains
aspects et mal employés, l’approche REST pourrait être vécue par vos utilisateurs développeurs comme
une régression par rapport au SOAP.

SOAP est une norme du consortium OASIS. Même si les normes ont l’inconvénient de parfois obliger à
des compromis contraignants, des implémentations pas toujours à l’état de l’art, et qu’elles ont tendance
parfois à ralentir l’innovation, il ne faut pas négliger une chose importante à propos de SOAP. Grâce à cette
norme, un large écosystème d’outils standards et interopérables s’est créé et a permis aux développeurs
de réaliser avant l’ère des microservices des intégrations dans une approche qu’on appelle SOA (Service
Oriented Architecture).

Voyons comment SOAP fonctionne du point de vue du cycle de vie des développeurs.

Ce qu’il faut bien comprendre dans SOAP, c’est qu’il est quasiment impossible d’appeler une API SOAP
existante sans générer du code métier à partir d’un fichier WSDL, car les flux échangés sont trop verbeux
pour être facilement créés depuis un code métier. Le seul avantage qu’ont les fichiers WSDL est qu’ils
permettent non seulement de générer du code pour effectuer les appels mais vérifient également que le
document transmis respecte bien le schéma XML. Nous verrons dans le chapitre sur la partie REST que,
d’une certaine façon, certains avantages de SOAP ont été perdus dans l’approche REST initiale.

Il y a essentiellement deux méthodologies pour construire une API SOAP. La première est appelée
"Schema First" ou parfois "Top-Bottom" et la deuxième est appelée "Code First" ou parfois "Bottom Up".

a. Approche Schema First

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -6-
 Mohamed Aziz Ben Mahmoud

Dans l’approche Schema First, le WSDL (étape 1) est défini via un simple éditeur de texte ou un éditeur
spécialisé WSDL. On génère, en étape 2, depuis le WSDL via un générateur de code les interfaces des
Webservices correspondants dans le langage du serveur (ici : Java). Puis on implémente le service (étape
3) et on déploie notre API sur un serveur applicatif (étape 4) de sorte qu’elle devienne disponible pour les
clients. Du côté client, on récupère depuis le serveur le WSDL qui fournit toujours les métadonnées
correspondantes aux services exposés (étape 5), puis on génère le code client d’appel dans le langage
que l’on souhaite utiliser côté consommateur (étape 6).

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -7-
 Mohamed Aziz Ben Mahmoud

Enfin, on peut écrire du code utilisant la librairie cliente (étape 7), qui va se charger de faire les appels au
serveur de façon transparente pour vous (sérialisations/désérialisations XML vers objets).

Les avantages sont que le contrat de l’API est conçu, généralement de manière plus précise et réfléchie, et
est moins dépendant d’une technologie ou d’un langage en particulier. À l’inverse, cela peut prendre plus
de temps, lorsqu’on est moins habitué par ce type d’approche.

b. Approche Code First

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -8-
 Mohamed Aziz Ben Mahmoud

Dans l’approche Code First, on commence par définir les interfaces de nos services, puis on implémente
directement les Webservices (étape 1). On déploie le Webservice (étape 2) sur un serveur applicatif de
sorte qu’on puisse appeler celui-ci et surtout extraire les métadonnées des services (WSDL).

À partir de là, le schéma d’appel pour la partie cliente est le même que pour l’approche Schema First.

L’avantage ici est la rapidité de mise en œuvre, car il y a moins de phases manuelles telles

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud -9-
 Mohamed Aziz Ben Mahmoud

que la définition assez fastidieuse du fichier WSDL. Il est cependant plus compliqué de paralléliser les
développements entre les clients et les serveurs, puisque le contrat du Webservice n’est généralement
stabilisé qu’à la fin des développements et que la définition des Webservices, étant moins conçue en
amont, a souvent tendance à changer.

La perception de SOAP en tant qu’usine à gaz a pour effet direct de retarder d’autant le "Time to First API
Call". Cette métrique est une donnée clé pour savoir si vous séduisez une communauté de développeurs
et permet de créer un écosystème autour de vos API.

Dans un monde très concurrentiel autour des plateformes SaaS, autant il est important d’avoir beaucoup
de clients, autant avoir l’adhésion des développeurs devient capital, car du nombre de développeurs qui
ont eu accès à vos API dépend souvent une qualité importante, une communauté qui va se développer
autour du produit comme un écosystème fertile.

Alors, finalement, pourquoi fournir une API SOAP n’est-il pas une bonne stratégie pour un éditeur SaaS
aujourd’hui ?

Une des raisons très souvent invoquées par les développeurs est que SOAP utilise un format XML et non
JSON. XML est en effet très verbeux et prend de la place dans le flux. Or, la plupart des flux modernes sont
gzippés, donc le poids compressé n’est plus très différent entre du JSON et du XML. Un autre argument
concerne la nécessité de faire du parsing entre le XML --> JSON et le navigateur qui supporte JavaScript.
Cet argument ne vaut que pour la partie communication backend --> frontend, et non pas pour des
intégrations entre différents backends qui, eux, savent gérer du XML. Enfin, une dernière raison est qu’il
n’est pas simple de faire un premier appel d’API en SOAP sans outillage très spécialisé, souvent intégré
dans les IDE ou en ligne de commande. À l’inverse une API REST simple de type lecture peut assez vite
être réalisée via un navigateur ou un outil léger tel que Postman.

Le principal problème est en réalité lié au fait que le SOAP n’est pas adapté aux architectures web
scalables. Le protocole HTTP est un protocole sans état. SOAP a été prévu pour maintenir des objets côté
serveurs (et donc avec une empreinte mémoire). Ainsi, lorsque vous créez un objet côté client, celui-ci
possède une image, une sorte d’hologramme mémoire sur lequel vous agissez via l’interface réseau.
Évidemment, entre chaque appel de méthode, le protocole a prévu que vous n’ayez pas besoin de recréer
cet "hologramme", ce qui diminue la consommation de la bande passante entre les multiples appels.
Même si cela peut paraître une bonne idée, cela en est une très mauvaise du point

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 10 -
 Mohamed Aziz Ben Mahmoud

de vue des architectures modernes dans lesquelles on souhaite de la haute disponibilité, qui passe
notamment par l’utilisation de Load Balancers. Mettre cela en place signifierait que nous devrions
systématiquement avoir des mécanismes de réplicas des objets entre les serveurs, ce qui est coûteux en
performance, ajoute une complexité à l’architecture, voire est totalement rédhibitoire au-delà de dizaines
de serveurs.

En résumé, les éléments suivants ont fait péricliter SOAP :

La complexité pour le développeur à concevoir le schéma et à manipuler la

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 11 -
 Mohamed Aziz Ben Mahmoud

chaîne d’outils.

Les GAFAM qui n’ont jamais fait la promotion de SOAP, car cela était incompatible avec les
architectures hautes disponibilités et scalables.

4. Les API REST

Wikipédia précise les origines de l’API REST :

Le terme representational state transfer a été défini pour la première fois en 2000 par Roy Fielding dans le
chapitre 5 de sa thèse de doctorat. La thèse de Fielding a expliqué les principes de REST auparavant connus
comme le « modèle objet de HTTP » depuis 1994 et qui ont été utilisés dans l’élaboration des standards
HTTP 1.1 et URI. Le terme est censé évoquer comment une application web bien conçue se comporte : c’est
un réseau de ressources (une machine à états virtuelle) au sein duquel l’utilisateur évolue en sélectionnant
des identifiants de ressources telles que [Link] et des opérations sur les
ressources telles que GET ou POST (des transitions d’état de l’application) transférant une représentation de
la ressource suivante (le nouvel état de l’application) vers l’utilisateur pour être utilisée.

Il est à noter que ce n’est que des années plus tard, vers 2007/2008 qu’ont commencé à apparaître
notamment chez les applications des GAFA telles que Google Maps, des appels simples à des ressources
HTTP pour intégrer des systèmes. Il n’était plus question de WSDL, de génération de code, mais de forger
une simple URL et quelques paramètres ou un corps de message simplifié pour faire de l’intégration
"Machine To Machine". Nous pouvons noter l’absence de validation formelle à partir d’un schéma, ce qui
peut conduire à des problèmes si vous n’avez pas inclus la validation des données dans vos couches
REST (ex. format d’un numérique, format d’une date…).

Pourtant, souvent considéré comme une libération pour les développeurs, les équipes R&D ont rapidement
déchanté et se sont rendu compte que faire un système complexe à partir de simples URL peut
rapidement devenir ingérable si quelques normes n’ont pas été mises en place. Ces dérives peuvent être
mitigées à partir d’une méthode qu’on appelle le niveau de maturité de Richardson.

Ce dernier indique qu’il y a quatre niveaux de maturités :

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 12 -
 Mohamed Aziz Ben Mahmoud

Niveau 0 : utilisation du RPC (Remote Procedure Call) en HTTP, sous une unique URL.

Niveau 1 : utilisation des ressources, avec plusieurs URL, mais sans l’utilisation des verbes.

Niveau 2 : utilisation des ressources, des verbes HTTP et des différents codes de retour.

Niveau 3 : utilisation d’une approche hypermédia via des liens intégrés dans les réponses.

Le niveau 0 n’est pas considéré comme une API REST, mais un simple et unique canal de communication
avec une seule URL dans lequel on fait passer des messages. On voit dans l’exemple ci-dessous qu’il n’y a
un qu’un seul service "appointmentService " qui utilise une méthode POST (pour pouvoir ensuite
gérer deux messages, un pour obtenir la liste des créneaux disponibles et un autre pour prendre rendez-
vous.

Le niveau 1 utilise plusieurs ressources identifiées, mais sans utiliser les verbes (en pratique, on utilise
donc uniquement les méthodes POST). Dans l’exemple ci-dessous, on récupère la liste des créneaux
disponibles du docteur mjones via une URL qui inclut une ressource (doctors /mjones ), tandis qu’une
autre API permet de prendre rendez-vous sur une autre ressource (slots /1234 ).

Le niveau 2 introduit l’utilisation de GET pour la partie lecture, POST pour la partie

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 13 -
 Mohamed Aziz Ben Mahmoud

insertion, tandis qu’on utilise les paramètres pour la partie filtrage.

Le niveau 3 introduit la notion de liens hypermédias, un peu à la manière des liens hypertextes dans les
pages web. Ainsi, lorsqu’on renvoie le résultat des créneaux du Docteur Jones, en dehors des données du
flux, sont envoyés un ou plusieurs liens hypertextes qui peuvent être utilisés pour continuer la
découverte des données, sans que le consommateur de l’API ait besoin de forger ces autres liens de
navigation.

Le niveau 3 paraît extrêmement prometteur mais dans les faits, le niveau 2 est déjà une belle avancée. En
effet, il est peu probable que votre client REST soit suffisamment intelligent pour arriver à suivre de
manière automatique les liens vers des API REST sous-jacentes en lisant juste les métadonnées comme
une balise <link> à la manière d’un internaute naviguant de lien hypertexte en lien hypertexte. D’autre
part, le niveau 3, très en vogue chez les architectes dans les années 2014-2015 n’a jamais vraiment eu une
implémentation de référence qui a favorisé son adoption, y compris le plus célèbre HATEOAS.

Si on en reste au niveau 2, il y a de très bonnes pratiques qu’il faut absolument respecter pour avoir des
API cohérentes :

Faire des choses simples :

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 14 -
 Mohamed Aziz Ben Mahmoud

Utiliser des termes standards, concrets et partagés et non des termes spécifiques au
métier ou des acronymes.

Ne jamais faire les choses de plusieurs manières, c’est-à-dire avoir plusieurs API qui
renvoient les mêmes résultats.

Concevoir l’API pour vos clients, pas pour vos données (i.e. penser les API comme une
exposition du métier plutôt que d’exposer un miroir reflétant la structure de votre base de
données par exemple).

Commencer par les cas d’utilisations les plus standards, puis les exceptions.

Granularité :

Les ressources ne doivent pas être imbriquées à plus de deux niveaux.

En outre, vous devez éviter les ressources imbriquées qui sont déjà une ressource :

/ usergroups / 25 / users / 123 --> Ici, l’utilisateur n° 123 doit avoir une
URL propre, référencée à partir du contenu renvoyé par l’API du groupe d’utilisateurs.

Répartition des rôles dans les API :

Path --> requis, identifiant de ressource.

Query --> optionnel, requête sur les collections avec du filtrage soit au niveau données
(filtrer les utilisateurs par exemple), soit au niveau des champs.

Body --> contient la logique spécifique à la ressource (notamment dans le cas des
créations où le Body contient les données de la ressource à créer).

Header --> global (clé d’API, métadonnées sur la requête...).

a. D’une application Single Page Application à une API First

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 15 -
 Mohamed Aziz Ben Mahmoud

Dans bien des logiciels SaaS, votre interface graphique sera constituée d’un frontend avec des
technologies dites "Single Page Application", permettant au navigateur de constituer un véritable logiciel
qui ne communique avec le serveur via des API REST que lorsqu’il en a besoin et non avec des
rafraîchissements de page pour chaque action. Les principales technologies devenues quasiment des
standards permettant cela sont Angular, VueJS ou encore ReactJS. On voit l’avantage en termes d’API :
comme le frontend ne communique que par API, toute donnée présente dans le frontend a dû être
exposée via des API REST. Si on ne va pas beaucoup plus loin, on peut considérer que ces API suffisent
pour un utilisateur qui voudrait faire de l’automatisation entre deux serveurs et non pas entre un
navigateur et un serveur. Or, ces API sont souvent développées uniquement dans le but de servir le
frontend, et non pas comme des API génériques qui pourraient aider n’importe quel développeur à créer
une application, avec une ergonomie différente ou encore qui voudrait interfacer des applications entre
elles. Ainsi, votre backend avec des API pourrait être parfait pour votre application web, mais se révélera
sans doute insuffisant et très peu pratique pour une application mobile avec une autre ergonomie ou des
besoins de performance très spécifiques. Il y a alors deux approches différentes et complémentaires :

L’approche "Back-End For Front-End". Elle consiste à créer des API spécifiques pour chaque
frontend, par exemple une pour votre application web, une autre pour votre application mobile
et une dernière pour certaines intégrations métiers avec des partenaires. Cette approche a
beaucoup d’avantages pour s’adapter aux besoins par rapport aux différents frontends, mais a
l’inconvénient d’aboutir très souvent à de la réplication de code et de ne jamais être exhaustive
pour un nième cas d’intégration.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 16 -
 Mohamed Aziz Ben Mahmoud

L’approche API First. Elle considère que l’on conçoit d’abord une API la plus générique possible
pour qu’elle puisse servir l’ensemble des frontends et tout autre usage. Le gros avantage est
que votre frontend devient une sorte de "démonstrateur" des possibilités de votre API. Vos
utilisateurs peuvent même aller jusqu’à pouvoir réimplémenter leurs propres pages en utilisant
vos API. C’est un cas d’usage de plus en plus fréquent pour les clients de type DSI qui
souhaitent intégrer le Best of Breed d’applications SaaS dans leurs propres processus et
portails internes.

Ainsi, dans le domaine de l’assurance ou des RH, il peut être intéressant pour les très grandes
entreprises d’utiliser des logiciels SaaS pour toute la logique métier backend extrêmement
complexe et de recréer un portail simple pour leurs utilisateurs, avec leur thème, leur
intégration propre et limitée à leur processus. Cela leur évite un portail "Sapin de Noël", pas
pratique et requérant de multiples clics entre les logiciels pour faire des actions métiers cross-
domaine (ex. un gestionnaire de contrat dans le domaine de l’assurance qui navigue entre un
logiciel de Prestation Santé et un logiciel permettant l’assurance de la voiture, pourtant pour le
même client). L’ergonomie devient unifiée pour leurs utilisateurs, alors que la DSI peut mener
son schéma directeur en maîtrisant les impacts sur les utilisateurs finaux. Paradoxalement, le
SaaS qui a été, à sa création, un enjeu d’achat pour les DSI, permet, grâce à l’approche API First,
de refaire une approche de construction pour les DSI. C’est donc un retour en grâce de la DSI
qui redevient un pourvoyeur de services métiers en se décorrélant de la complexité

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 17 -
 Mohamed Aziz Ben Mahmoud

technique, qu’il délègue au meilleur fournisseur SaaS sélectionné.

b. La documentation d’une API

Lorsque vous réalisez que votre logiciel comporte des centaines de tables et des centaines d’API, vous
vous poserez rapidement la question de savoir comment documenter ces API pour vos utilisateurs.

En Java, il y a un moyen simple d’extraire la documentation à partir du code Source via la Javadoc, ce qui
évite les nombreuses erreurs de désynchronisation qui se produise lorsque vous constituez une
documentation de façon séparée. La Javadoc a également un énorme avantage car elle uniformise
l’ensemble des documentations des librairies Java. Ainsi, chaque développeur est beaucoup plus
productif pour ajouter une nouvelle librairie car il se repère plus vite dans les documentations. C’est un peu
le principe de Wikipédia où l’homogénéité de la forme des articles rend la lecture et la prise d’information
beaucoup plus rapides.

Dans le monde des API, plusieurs tentatives de standardisation ont eu lieu autour des années 2012-2015
(RAML, Blueprint, Swagger). C’est finalement Swagger avec sa normalisation autour d’OpenAPI (en version
3.0.3 à l’heure actuelle) qui a pris l’ascendant chez les développeurs.

Swagger/OpenAPI a plusieurs modes d’utilisation que nous allons détailler, mais voyons la plus simple. À
partir de votre Framework préféré (ex. Spring Boot, .NET Core), vous allez annoter les classes qui
participent à l’exposition de vos API REST. Un générateur va alors vous permettre de produire à la fois un
fichier de définition de vos API (au format YAML ou JSON) ainsi qu’une documentation HTML. Cette
documentation est dynamique et peut notamment servir à tester directement les API sur des serveurs de
démonstration par exemple, ce qui augmente l’attractivité pour les développeurs qui peuvent facilement
tester vos API et les adopter.

Beaucoup d’éditeurs SaaS qui ont fourni des API avant la popularisation d’OpenAPI sont obligés de
maintenir un outillage propriétaire ou obsolète alors qu’OpenAPI fournit désormais un écosystème
complet et standardisé pour tous les usages.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 18 -
 Mohamed Aziz Ben Mahmoud

Exemple de l’api exemple pour Swagger UI

Cette approche via OpenAPI est vraiment séduisante mais peut être encore améliorée pour arriver à
retrouver le même niveau d’intégration et de productivité que l’on avait avec les SDK des années 90.

En effet, voici le processus d’appel d’une API sans approche SDK :

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 19 -
 Mohamed Aziz Ben Mahmoud

On observe tout de suite les limitations : les développeurs vont consacrer beaucoup de temps à l’écriture
des clients HTTP permettant l’appel des API dans leur langage de prédilection, la gestion du parsing des
réponses vers des objets métiers et enfin la gestion des exceptions. S’il y a 100 API à appeler, il faudra
faire 100 fois ce travail long et fastidieux. Si on souhaite l’intégrer depuis un autre langage (ex. .NET), cela
va doubler le travail. Enfin, en cas de légère variation de l’API, le client développé pourrait ne plus
correspondre à l’API Serveur.

Or, on sait très bien que la plupart des intégrateurs utilisent des langages classiques, tels que Java, .NET,
Python, JavaScript… Pourquoi ne pas aller un cran plus loin en simplifiant encore l’intégration ? C’est ce
que nous proposons avec l’approche SDK/OpenAPI.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 20 -
 Mohamed Aziz Ben Mahmoud

Dans cette approche, l’idée est que la documentation de l’API ne soit pas le seul livrable formant
l’articulation entre le fournisseur des API et le consommateur, mais qu’elle soit accompagnée des
librairies dans les langages les plus usuels pour les développeurs. OpenAPI étant une norme, un grand
écosystème s’est créé autour de cette technologie et notamment la génération automatique des clients
dans plusieurs technologies et langages. SmartBear, éditeur autour d’OpenAPI a sa solution payante, mais
il existe des alternatives open source telles que OpenAPI Generator, qui est capable de générer des clients
HTTP pour les API OpenAPI dans une trentaine de langages environ. On trouve aussi des générateurs chez
des acteurs Cloud tels que Microsoft Azure avec AutoRest

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 21 -
 Mohamed Aziz Ben Mahmoud

(mais qui est indépendant de l’utilisation d’Azure).

Dans cette approche, nous recommandons de fournir, en complément de vos services, des librairies pour
les principaux langages utilisés par les Entreprises. Dans notre exemple, nous avons décidé de fournir des
clients Java, JavaScript, .NET Core, Go, TypeScript, Python et PowerShell. Ces librairies peuvent être mises
en open source, car elles ne possèdent pas de logique métier, mais uniquement les codes d’appels à vos
fonctions métiers.

Dans cette logique, le développeur qui souhaite utiliser vos API n’a besoin, en théorie, que d’ajouter la
librairie cliente de vos API dans le langage de son choix et de l’intégrer via un système de dépendance
(Maven, Gradle, NuGet, NPM…). Il n’a alors plus qu’à écrire quelques lignes de code, pour lesquelles il sera
aidé par la complétion de son IDE préféré. Il va ensuite manipuler des objets typés et n’aura plus à gérer
manuellement la création des clients HTTP, la sérialisation/désérialisation des flux JSON et des objets
métiers liés à l’API. Une API même relativement complexe peut, grâce à ce mécanisme, s’appeler en
quelques lignes de code. Si votre client souhaite utiliser un langage non supporté, il aura toujours la
possibilité d’utiliser les API REST.

Le temps d’appel de la première API est réduit, et la productivité des utilisateurs de vos API est nettement
améliorée.

Ce n’est pas un hasard d’ailleurs si tous les Cloud Providers fournissent leurs services, non seulement via
des API en mode REST, mais également via des clients d’API pour la plupart des langages. Azure a utilisé
pour les API de son Cloud la même approche décrite ici via son projet Unirest.

Cette approche SDK a également une vertu intéressante : celle de pouvoir être utilisée par vos propres
équipes de développement au minimum à trois endroits. En effet, si vous avez une UI, il est probable que
vous appeliez des API côté backend. En normalisant vos API avec OpenAPI et en générant les clients, vous
bénéficierez d’une sécurité accrue des appels, notamment en ce qui concerne les traitements toujours
délicats des exceptions directement dans la couche UI. Sur la partie backend, pour les appels entre
microservices, vous pourrez également bénéficier de cette librairie. Enfin, vous pourrez utiliser vos clients
OpenAPI pour les tests en Behaviour Driven Development qui testeraient des API.

Dans l’exemple ci-dessous, nous avons développé un serveur d’applications en .NET Core, qui expose via
OpenAPI des services. Trois SDK ont été créés (un en TypeScript qui va permettre d’accélérer les
développements sur la partie frontend en Angular, un en

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 22 -
 Mohamed Aziz Ben Mahmoud

JavaScript qui va permettre d’accélérer les développements sur la partie Tests/Cucumber, tandis que le
dernier pourra faciliter la création d’une autre application web qui fait appel aux API du serveur en .NET
Core grâce à un SDK Java).

c. Test-First et approche SDK

Lorsque vous appliquez la méthode BDD (Behaviour Driven Development) - évoquée dans le chapitre Le
DevOps au service du SaaS - pour tester vos API, au moment de l’écriture des appels réels correspondant
aux lignes de Gherkin (DSL du framework Cucumber permettant de rédiger les tests cases en Give-When-
Then, vous aurez besoin également d’initialiser et de configurer des clients HTTP. Or, il serait dommage
d’écrire du code d’appel HTTP à la main (ainsi que le mapping de tous les objets correspondants).

Nous proposons donc l’approche méthodologique suivante :

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 23 -
 Mohamed Aziz Ben Mahmoud

Écrire le YAML OpenAPI avec un éditeur (Design First).

Générer les clients OpenAPI.

Créer les tests en BDD (Gherkin mais sans l’implémentation des tests).

Importer la librairie cliente de l’étape 2, de sorte de réutiliser les classes d’appels et les objets
DTO.

Finaliser les appels aux API dans les tests BDD.

Lancer les tests qui doivent échouer (puisqu’aucun service n’a été développé).

Créer le code serveur correspondant au YAML. Il y a deux méthodes pour y arriver. La première
consiste à écrire manuellement l’ensemble du code serveur et faire en sorte que le résultat des
API générées soit conforme aux API définies en étape 1 (il suffit de générer le métamodèle lors
de l’exécution et vérifier qu’il est le même). L’autre méthode consiste à passer par des
générateurs de code serveur. Ces générateurs sont moins évolués que leur équivalent côté
client et fonctionnent en produisant dans le langage cible les interfaces permettant les appels
d’API : vous n’avez plus alors qu’à implémenter la logique métier.

Implémenter la logique métier dans le code serveur.

Lancer les tests et corriger l’implémentation tant que cela n’est pas au vert.

Refactorer pour améliorer la maintenabilité du code dans le temps !

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 24 -
 Mohamed Aziz Ben Mahmoud

5. Des limites d’OpenAPI et l’approche GraphQL

Une des limites d’OpenAPI est liée au fait que chaque API est dédiée à la récupération d’informations
autour d’un concept de ressources (on ne récupère pas via une seule API l’ensemble des informations de
la base de données, sinon on aurait à la fois des problèmes de performance et d’encombrement sur le
réseau). Or, si votre application ou votre intégration nécessite de récupérer différentes ressources
accessibles depuis plusieurs API (ex. une application nécessitant de créer une facture aura besoin d’API
pour la liste des éléments d’une commande, d’une API pour la description des produits, d’une

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 25 -
 Mohamed Aziz Ben Mahmoud

API d’adresse de facturation et de livraison), vous risquez de devoir envoyer des dizaines, voire des
centaines de requêtes HTTP sur les différents services. Ces multiples appels peuvent être facturés,
générer une charge importante et, dans un contexte d’application mobile, induire des problèmes de
surcharge ou de latence réseau. Dans le cas où vous fournissez de nouvelles API proposant des
combinatoires de ressources liées afin de simplifier les appels, vous vous exposez à devoir maintenir des
dizaines ou des centaines d’API supplémentaires. En termes de couverture fonctionnelle, il manquera
toujours soit une ressource soit un attribut pour tendre vers une requête unique.

C’est là que GraphQL peut constituer une solution à considérer. GraphQL a été initialement créé par
Facebook pour répondre à des problématiques liées à leurs applications mobiles, où le nombre de
requêtes réseau doit être nécessairement limité si on veut avoir une latence faible et préserver la batterie.
Le client envoie une requête qui demande au serveur une agrégation côté serveur des différents domaines
sous une réponse unique : ainsi, on évite au client d’effectuer plusieurs requêtes et de devoir également
agréger les données entre elles.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 26 -
 Mohamed Aziz Ben Mahmoud

En ce sens, GraphQL est une sorte de SQL avec des mécanismes proches des jointures, mais en se basant
sur des ressources ou d’autres API et non pas des données brutes issues de la base. C’est très important
car cela vous permet de ne pas contourner toutes les couches métiers placées au-dessus de la couche de
stockage. De ce fait, l’agrégation extrêmement rapide côté serveur simplifie grandement l’utilisation côté
client, notamment les clients mobiles, qui peuvent bénéficier d’une réponse très dynamique grâce à
GraphQL.

GraphQL a bon nombre d’autres avantages par rapport à une API REST :

GraphQL est une spécification tout comme l’est SQL, ce qui rend l’utilisation et l’outillage plus
homogènes que les API REST.

Lorsque vous faites une API REST, vous renvoyez un flux de données avec une grappe d’objets
JSON, mais il y a relativement peu de mécanismes pour influer sur le choix des données. Or
GraphQL impose de préciser chacune des propriétés et chacun des agrégats que vous
souhaitez récupérer (un peu comme si le SQL ne permettait pas l’utilisation du * dans SELECT
* mais uniquement SELECT

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 27 -
 Mohamed Aziz Ben Mahmoud

field1, field2 …). Cela permet de connaître beaucoup plus finement les usages de vos
clients, voire de vous apercevoir qu’une partie des données n’est jamais utilisée, ce qui vous
permettra de changer vos API sans prendre le risque d’impacter vos clients.

Même si cela semble une promesse incontournable, nous ne recommandons pas une approche 100 %
GraphQL. L’utilisation de GraphQL côté client n’est pas aussi simple qu’une requête GET sur le navigateur
ou sur un outil comme Postman, ce qui risque de vous ralentir dans l’élaboration de vos API pour vos
utilisateurs. GraphQL oblige à apprendre un nouveau langage à la fois pour vos propres équipes et aussi
pour vos clients. Mais surtout, les requêtes GraphQL, via la facilité d’écriture des requêtes, peuvent poser
les mêmes problèmes de performance que les mappeurs Objet-Relationnel et faire effondrer votre
système. En résolvant le graphe des données à récupérer, le moteur GraphQL peut être amené à faire un
premier appel à un backend, puis à plusieurs en cascade et ensuite à agréger l’ensemble. La multiplicité
des appels réseau entre les différents backends et un agrégat retourné potentiellement trop lourd peut
générer un effondrement de performance.

Il existe quelques parades comme de mettre en place des limites sur la complexité de requêtes
notamment sur le nombre de jointures mais ils sont très approximatifs (tout autant que de savoir à
l’avance si une requête SQL va être rapide ou lente en fonction du nombre de jointures).

Facebook, conscient du problème, est même quelque part revenu en arrière puisqu’au lieu d’exposer une
API GraphQL du point de vue du client, il préfère fournir une liste de requêtes prédéfinies et validées
comme étant performantes au niveau de leur serveur, et permettre l’exécution uniquement de certaines
requêtes identifiées.

Évidemment, l’écosystème autour de GraphQL peut bouger et changer la donne dans quelques années. Il
faut donc considérer GraphQL comme une offre complémentaire à votre portail d’API qui peut vous
permettre de mettre rapidement à disposition des données de façon structurée et être un allié très
intéressant pour le Time to Market.

6. Gestion des API

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 28 -
 Mohamed Aziz Ben Mahmoud

a. API Gateway

Lorsque vous exposez des API, vous souhaitez pouvoir les monitorer (nombre d’appels) pour pouvoir soit
limiter leur usage (throttling), soit facturer à l’usage. Dans le cas où vous n’avez pas une approche Zero
Trust Architecture (cf. 5.7 Patterns Réseau) et que vos services discutent en HTTP en interne, vous
souhaitez par exemple avoir du SSL Offloading ou encore la prise en charge des tokens d’authentification.
Vous ne souhaitez pas forcément que chaque service ait cette responsabilité et, dans ce cas, vous pouvez
opter pour une brique appelée API Gateway qui va implémenter et simplifier ces mécanismes transverses
à toutes les API.

Avec l’émergence des architectures microservices, plusieurs acteurs se sont positionnés sur ce secteur et
vous en trouverez disponibles en SaaS tels que le très complet, mais cher, Google Apigee, ainsi que
d’autres acteurs historiques tels que MuleSoft ou Axway. À l’inverse, certains architectes préfèrent
implémenter pour chaque service une API Gateway intégrée au service backend. Dans cette approche,
nous retrouvons des Frameworks tels que Spring Cloud Gateway dans le monde Java ou le Framework
Ocelot dans le monde .NET. Nous préconisons, sur des nouveaux développements, d’éviter d’avoir une
Gateway externe, notamment pour des questions de coûts car tous les Frameworks modernes peuvent
intégrer ces mécanismes. Sur des applications plus anciennes, il peut être plutôt judicieux de venir
apposer une brique

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 29 -
 Mohamed Aziz Ben Mahmoud

externe qui va fédérer et éviter d’ajouter dans chacun des backends les services transverses.

Parmi les mécanismes peu connus et pourtant essentiels pour la résilience de votre système d’API,
souvent proposé par l’API Gateway, il existe les mécanismes de throttling.

b. Throttling

Le mécanisme de throttling (ou resserrement/limitation en français) est un mécanisme défensif à mettre

De ce fait, les applications peuvent être correctement dimensionnées par rapport aux utilisations via l’IHM.
De même, en ce qui concerne les batchs de nuit, ceux-ci sont généralement planifiés et espacés durant la
nuit et tiennent compte des volumes qui sont échangés. Ce n’est en revanche pas le cas des API où vous
pouvez avoir des utilisations totalement hors de contrôle en termes de nombre d’appels simultanés car ils
sont effectués par un programme côté client potentiellement bogué. Cela pourrait donner in fine les
mêmes résultats qu’une attaque de DDoS (déni de service) par un pirate, mais sans que ce soit
malveillant.

Les problèmes d’API sont bien souvent très proches des problèmes de Sélection N + 1 dans notre chapitre
dédié à la performance : en effet, il suffit par exemple qu’un développeur client de votre API appelle une
API demandant la liste des utilisateurs, puis pour chacun d’eux relance l’API pour obtenir de grandes
quantités de données (telles que des listes de commandes de chacun des utilisateurs). Cela aurait pour
conséquence des centaines de milliers d’appels d’API en quelques secondes, là où l’équivalent au niveau
IHM ou Batch de nuit aurait été atteint en quelques heures.

Face à cette menace qui concerne également les API utilisées dans le cadre du Cloud, le principe est de
mettre en place un mécanisme de protection. Ce mécanisme n’est souvent pas mis au niveau de chaque
API, mais sur l’API Gateway, afin de limiter la pression globale sur le système. Lorsque les envois de
requêtes dépassent les limites fixées de débit, l’API Gateway renvoie une erreur aux nouvelles requêtes via
le statut HTTP 429

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 30 -
 Mohamed Aziz Ben Mahmoud

Too Many Requests au client. Lors de la capture de ces exceptions, le client peut attendre, puis
renvoyer les demandes en échec de façon à respecter les limitations de débit de l’API Gateway.

Au-delà des problèmes de pression sur votre système, c’est un bon moyen pour vos utilisateurs en cas de
facturation au nombre d’appels d’éviter des factures anormales liées à une mauvaise utilisation.

Voici un petit aperçu des différents types de throttling que vous pouvez mettre au niveau de la plateforme
d’API :

Un throttling global sur l’ensemble de la plateforme, afin d’éviter que l’utilisation de l’API ne
perturbe l’ensemble de vos utilisateurs et de vos tenants SaaS.

Une limitation par client, par exemple une limitation de 500 requêtes par tranche de 5 minutes
(Politique d’Atlassian pour les API Jira et Confluence).

Une limitation sur certains groupes d’API particulièrement consommatrices.

c. Back-Pressure

Au lieu d’avoir une exception et de ne répondre qu’à une partie du trafic, il existe deux manières de gérer
les pics de charge. La première est très classique et consiste à mettre en place des buffers (files
d’attente). La deuxième est plus récente et consiste à ce que le système appelé contrôle la vitesse du
système appelant : cette méthode est appelée Back-Pressure.

Le principe est que vos clients soient avertis dans le flux de réponses qu’ils exercent une pression trop
importante sur le système et qu’ils devraient limiter le nombre d’appels sans être obligés de renvoyer
brusquement une erreur HTTP 429.

Imaginez un système A qui envoie 100 requêtes par seconde à un système B, mais que le serveur B ne
peut gérer que 75 requêtes par seconde. Le système B peut bufferiser mais, à un moment donné, le buffer
sera plein et vous risquez de tomber à court de mémoire. Nous pourrions utiliser le throttling mais, en ce
qui concerne les API externes, nous allons chercher une implémentation plus élégante pour éviter la
rupture de service.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 31 -
 Mohamed Aziz Ben Mahmoud

L’option idéale pour le serveur B serait de pouvoir avertir le système A qu’il est surchargé et qu’il faudrait
limiter le nombre de requêtes. Si le système A est un utilisateur, cela correspond aux cas d’usage que l’on
retrouve sur certains sites à fort pic trafic tels que les billetteries, la SNCF ou Doctolib qui ont intégré dans
leur interface graphique un système de queue indiquant à l’utilisateur de revenir plus tard.

L’une des fonctionnalités essentielles du Back-Pressure est donc de pouvoir décider à quel endroit le
buffering est le plus judicieux : en effet, lorsqu’un buffer est placé au milieu d’une chaîne de traitement, il
devient complexe de communiquer l’information à tous les appelants qui vont donc continuer à se
présenter sur le système et à le stresser encore plus. Dans le cas de la billetterie, même si celle-ci est
composée de plusieurs sous-systèmes (gestion du placement, gestion du paiement, édition du billet), il y a
un mécanisme qui remonte l’information de proche en proche pour placer le buffer au niveau des
utilisateurs et non pas au milieu du processus de placement, ce qui créerait des erreurs de buffer plein et
ne serait pas compréhensible par les utilisateurs.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 32 -
 Mohamed Aziz Ben Mahmoud

Si l’appelant à l’origine est un batch, les conséquences sont faibles puisque la vitesse du batch va
s’adapter à la vitesse du maillon le plus faible et ralentir son rythme (dans une certaine mesure).

Pour mettre en place la back-pressure, il existe deux modèles : push et pull, mais dans tous les cas, ces
deux modèles sont disponibles sous forme de librairies dans la plupart des langages. Les plus connus
sont [Link] Stream, RxJS, ou RxJava.

d. Les API asynchrones

En plus des mécanismes expliqués plus haut, il y a une fonctionnalité de base qu’il faut toujours mettre en
place afin d’éviter l’effondrement du système : il s’agit du principe de timeout.

Si vos API ont des temps de traitement longs et que vous avez une API synchrone, alors le timeout va se
déclencher régulièrement. Dans le cas où votre application procède à des appels successifs synchrones
sur une chaîne de microservices, vous devenez dépendant d’une défaillance de l’un des maillons de la
chaîne.

C’est ce qui se produit dans le diagramme suivant où trois microservices sont impliqués :

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 33 -
 Mohamed Aziz Ben Mahmoud

La meilleure manière de se prémunir de cela est de passer à une architecture asynchrone et orientée
message. Au lieu d’indiquer par exemple via un code HTTP 201 qu’un objet est créé, vous pouvez utiliser
le code HTTP 202 indiquant que la requête a été prise en compte mais pas encore traitée.

Dans ce cas, l’API enregistre votre action, crée un message en interne généralement en utilisant un
middleware de message (ex. RabbitMQ) puis rend la main rapidement car il n’a pas besoin de traiter le
message tout de suite.

Ensuite, un mécanisme tel qu’un worker va se charger de dépiler les messages. Pour que le client soit
averti que l’action a réellement été effectuée, soit il va interroger régulièrement (principe du pulling) auprès
d’une API dédiée si le traitement a bien été effectué, soit il utilise un mécanisme de notification (mode
push) tel que Signal/R chez Microsoft ou des Web Socket.

Vous pourriez être tenté d’exposer directement votre bus de données pour proposer une approche
asynchrone. Néanmoins, cela va obliger votre consommateur à connaître un nième protocole en plus du
protocole HTTP et à gérer une autre documentation sur les

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 34 -
 Mohamed Aziz Ben Mahmoud

formats de message attendus et possibles. Voilà pourquoi il nous semble utile de toujours proposer une
API synchrone qui se charge, elle, d’effectuer cette opération.

L’utilisation de l’asynchronisme et des bus de données tels que RabbitMQ ou Kafka (qui offre des
possibilités supplémentaires telles que le stockage à long terme des messages) est un levier pour créer
des applications robustes ; nous recommandons l’usage des patterns tels que le publish/subscribe pour
découpler votre architecture. Le livre "Java Spring - Construisez vos applications réactives avec une
architecture microservices en environnement Java EE" aux éditions ENI détaille ce type de patterns.

e. Montée de version des API

Dans le cycle de vie de vos API, un opérateur SaaS est amené à faire évoluer régulièrement ses API, ce qui
devient une opération impactante à partir du moment où le parc client est développé.

Il existe trois façons de faire lorsque vous avez besoin de modifier une API qui casserait la compatibilité
avec les API existantes.

Casser la compatibilité

C’est le mode le plus brutal et qui ne tient pas compte des utilisateurs. C’est le plus souvent une
conséquence involontaire, généralement lors d’évolutions qui n’auraient pas dû casser a priori la
compatibilité ascendante, mais qui a eu en réalité des impacts. Le problème est que cela crée un couplage
fort entre votre modification, la mise en production et la nécessité pour tous les clients de vos API de
migrer instantanément, ce qui n’est généralement pas possible. Voilà pourquoi nous recommandons de
mettre en place un mécanisme de versioning.

Versioning

Généralement, c’est l’approche qui est retenue. Au lieu de mettre un seul point d’entrée des API, par
exemple [Link] vous allez systématiquement placer vos API dans des versions
majeures (les versions mineures ne devant pas casser la compatibilité), par exemple
[Link] pour votre première version d’API et [Link] pour
votre deuxième version. Il est à noter que cela va souvent vous obliger à dupliquer une partie de votre
code métier, car il est dangereux de coupler le code de la V1 et celui de la V2 : en cas d’évolution du code
métier de la V2, vous

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 35 -
 Mohamed Aziz Ben Mahmoud

pourriez faire involontairement des modifications sur la V1 et casser la compatibilité.

Nouveau module ou domaine

Parfois, la nouvelle version n’est pas vraiment une V2 ou une V3, mais une approche différente, avec une
modification profonde du domaine métier : il est alors préférable de créer une nouvelle API exposant votre
domaine que d’essayer de maintenir la logique initiale de V1/V2/V3. Par exemple, dans le cas où vous
auriez exposé il y a plusieurs années l’API [Link] et que vous décidez de la
découper en deux parties acheteurs et vendeurs, il serait plus simple de créer deux API, par exemple
[Link] et [Link]

f. Gérer le cycle de vie des API

Une fois que vous avez géré correctement le versioning de vos API, il est nécessaire de gérer la fin de vie
des anciennes versions.

Il faut avoir en tête que garder plusieurs versions d’API va non seulement vous coûter en maintenance (les
coûts sont a minima proportionnels au volume de code et de Feature) mais aussi vous obliger à réfléchir à
des compromis sur la maintenance de la compatibilité. Au-delà des coûts, la compatibilité est antagoniste
à l’évolutivité et donc à vos capacités d’innovation. À l’inverse, une agressivité trop importante dans la
dépréciation pourrait vous faire perdre le soutien des développeurs, ce qui est très précieux quant à
l’adoption de votre produit.

Pour cela, il est important qu’à chaque nouvelle version des API, vous communiquiez auprès de vos clients
un document récapitulatif présentant les cycles de vie de vos API :

Le fait que votre API N - 1 sera dépréciée à partir de telle date.

Le fait que cette API N - 1 sera supprimée à partir de telle date.

Une fois cela fait, il ne faut pas juste attendre patiemment que les clients sautent le pas volontairement et
réécrivent une partie de leurs logiciels spécifiques pour les adapter à votre nouvelle API. En effet, vous ne
pourrez pas couper le service du jour au lendemain même en ayant prévenu en amont. Il va falloir convertir
votre base client à l’utilisation de ces nouvelles API. Pour cela, il faut non seulement que celles-ci amènent
de la valeur mais également que vous apportiez du support et un accompagnement à travers l’équipe
"Run", chargée de répondre aux sollicitations utilisateurs. En mettant en place un monitoring de

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 36 -
 Mohamed Aziz Ben Mahmoud

l’utilisation d’une API en version N-1 et version N, vous devriez avoir une courbe de décroissance de
l’utilisation de l’ancienne API et une autre courbe de croissance de l’utilisation de la version N. C’est à une
équipe conjointe de la R&D et du Run de prendre en charge l’atteinte des objectifs de suppression de ces
API dans le temps imparti.

Dans la pratique, une API ne doit pas être retirée sous moins de six mois ; un cycle d’au moins un an à
deux ans semble être un bon compromis.

7. Conclusion

La stratégie sur les API doit être clairement appréhendée à tous les niveaux de l’entreprise et ne pas rester
comme un détail concernant la R&D. La demande d’API devient croissante notamment à travers la
généralisation des approches de type Low-Code (Zapier, Integromat). De votre bon ou mauvais
positionnement sur ce sujet dépendra votre courbe de croissance sur les prochaines années, tout comme
le SaaS a été un relais de croissance après le modèle classique On Premise.

Nous préconisons d’avoir non seulement des API REST, accessibles et testables via un portail orienté pour
les développeurs mais aussi pour les "Citizen Developers" dans le cas des outils Low Code. Les
compléments de type GraphQL et la fourniture de SDK prêts à l’emploi sont des accélérateurs et des
différenciants à l’adoption de vos services : il faut désormais les considérer comme tels. Attention,
toutefois, GraphQL est à considérer comme une mise en œuvre en second temps de manière à ne pas
cannibaliser votre portail d’API REST ; celui-ci doit être un premier niveau de maturité avant de pouvoir le
réexposer sous la forme d’un portail GraphQL. Enfin, le cycle de vie doit être géré et non pas subi par vos
clients, sous peine de retrouver les mêmes problèmes d’obsolescence et de maintenance qu’on pouvait
trouver en On Premise versus le SaaS.

© Editions ENI - Tous droits réservés - Copie personnelle de Mohamed Aziz Ben Mahmoud - 37 -