Une introduction à l'API first
Publié le 11 août 2022 par Andrew Owen (6 minutes)
L’article de cette semaine est l’extension longtemps promise de la conférence éclair que j’ai donnée à SUGCON 2022 à Budapest. Si vous venez de découvrir le sujet, vous pouvez lire mes articles précédents sur Jamstack et MACH et architectures pilotées par les événements.
En tant que développeurs, vous êtes probablement familiarisés avec toute cette terminologie. Mais au cas où des lecteurs non initiés seraient tombés sur ce document, je vais expliquer les termes au fur et à mesure, en commençant par les interfaces de programmation d’applications (API). Au niveau le plus élémentaire, une API décrit la manière dont deux processus logiciels ou plus communiquent. Ces processus peuvent exister au sein d’un même logiciel fonctionnant sur un même ordinateur, ou dans plusieurs programmes sur plusieurs ordinateurs.
Comme de nombreux éléments du développement moderne, les API peuvent être publiques ou privées. Les API publiques fournissent une interface externe permettant aux logiciels tiers d’interagir avec le système. Les API privées sont utilisées exclusivement en interne. Même dans les logiciels monolithiques (un seul grand programme), vous pouvez trouver les deux types d’API. Mais dans les solutions distribuées, où les composants logiciels s’exécutent sur plusieurs systèmes, il est essentiel de disposer d’un moyen bien défini de communication entre les composants.
Le portail API de SE Basic IV fournit une illustration simple des API publiques/privées. Le menu de gauche contient une liste de tous les modules, et chaque module contient une liste de toutes les routines qui peuvent être appelées. La plupart de ces routines sont destinées uniquement à un usage interne par le microprogramme (dans un monde idéal, elles seraient toujours entièrement documentées pour faciliter la maintenance du logiciel). Cependant, les routines du module Vectors sont différentes. Il s’agit des API publiques. Les API privées sont susceptibles d’être modifiées, mais les API publiques sont fixes.
Il s’agit d’un langage d’assemblage, de sorte que la table des vecteurs garantit que même si les routines se déplacent dans la mémoire dans les versions ultérieures du logiciel, il existe une adresse fixe pour appeler chaque routine. Les paramètres ne changent pas. S’il existe une meilleure façon de faire quelque chose, un nouveau point de terminaison de l’API (routine) est ajouté, mais l’ancien reste en place. Nous disons qu’il est déprécié: cela signifie qu’il ne faut pas l’utiliser. Mais il est toujours là au cas où un logiciel en dépendrait. Les points de terminaison d’API obsolètes ne doivent être supprimés que si vous êtes certain qu’aucun logiciel utilisé qui en dépend ne peut être facilement mis à jour pour utiliser le nouveau point de terminaison.
Selon le moment où vous lisez ceci, il se peut que vous ne voyiez que l’API du système de fichiers dans la liste (l’API de la console sera introduite dans la prochaine version bêta). Ces points de terminaison sont conçus pour faciliter l’utilisation par les programmeurs en langage assembleur. Ils encapsulent une tâche individuelle, telle que le chargement d’un fichier du disque vers la mémoire. En fait, pour effectuer cette opération, plusieurs appels doivent être faits à une API de disque de niveau inférieur. Mais le programmeur ne devrait pas avoir à se préoccuper de la gestion de la poignée de fichier, de l’ouverture du fichier, de la lecture des statistiques du fichier, de la lecture du fichier à partir du disque, puis de la fermeture du fichier. Au lieu de cela, le programmeur transmet un chemin d’accès au fichier et l’adresse en mémoire où le fichier doit être chargé. La routine se charge du reste, y compris de la gestion des erreurs (par exemple, si le fichier est trop volumineux pour tenir dans la mémoire à l’adresse donnée).
Mais c’est de l’ancienne école. La plupart du temps, lorsque nous parlons d’API, nous parlons d’API Web, généralement ce que l’on appelle des API RESTful, définies dans une sorte de schéma, tel que OpenAPI, ou dans une collection Postman, utilisant des méthodes HTTP, avec des charges utiles dans des enveloppes JSON. Cela fait beaucoup à décortiquer.
JavaScript est le langage des applications web, et JSON est un sous-ensemble d’objets JavaScript. Si vous êtes familier avec CRUD (créer, lire, mettre à jour, supprimer), REST fait quelque chose de similaire en utilisant des méthodes HTTP (POST, GET, PUT/PATCH, DELETE). Un schéma d’API est un moyen d’organiser les API.
Les API:
Lorsque l’on parle d’API-first, on entend souvent dire que les API sont des citoyens de première classe. Dans sa forme la plus simple, cela signifie que le produit est divisé en une solution dorsale qui fournit des API et une application client qui consomme ces API. La priorité est censée être donnée à la création d’API cohérentes et réutilisables. Bien qu’en pratique, les API sont souvent créées de manière ad hoc, et un pauvre rédacteur technique est censé documenter le résultat (à mon avis, ce n’est pas l’API-first).
J’irais même jusqu’à dire que dans un véritable environnement de développement “API-first”, les API devraient être conçues avant que quiconque ne commence à écrire du code. Mais l’un des avantages des API est que si vous vous trompez la première fois, vous pouvez créer une nouvelle API et supprimer l’ancienne, avec un peu de chance sans rien casser. Cela devient de plus en plus important à mesure que de nouvelles normes émergent, telles que les API bancaires et commerciales, et que les grandes entreprises acquièrent de plus petites sociétés et cherchent à intégrer les produits dans une expérience d’API unifiée.
Par ailleurs, j’ai souvent vu des startups qui réussissaient la plupart des choses, mais qui ne documentaient pas les API. Les clients ont alors du mal à comprendre comment les utiliser. Les développeurs détestent rédiger des documents, c’est pourquoi je pense que la meilleure approche consiste à spécifier l’API et à la confier au développeur. Mais bien sûr, les développeurs devraient avoir leur mot à dire dans la conception de l’API en premier lieu. C’est ce que je propose:
Le deuxième niveau de l’API-first est celui des microservices. Ces composants doivent être aussi atomiques que possible et complètement remplaçables. En réalité, de nombreuses organisations qui prônent la priorité aux API ont encore beaucoup de logiciels monolithiques à prendre en charge. Mais il est possible d’adapter une API à un logiciel plus ancien. Et si vous y parvenez, vous pouvez remplacer les composants un par un par des microservices jusqu’à ce que votre solution ne soit plus monolithique.
Mais les API ne sont qu’un début. Il y a aussi:
Mais cet article est déjà long, et ces sujets feront l’objet d’articles ultérieurs.