Conception d'API : construire correctement une interface de programmation d'applications

Problèmes courants de conception d'API

Le débat REST contre SOAP constitue un exemple de cadre contraignant pour les API. Lorsque des applications dépendent déjà des unes ou des autres, toute nouvelle API doit évidemment se fondre dans le moule. Ce qui est moins évident, c'est que la plupart des API font partie d'une tendance allant vers le fractionnement en composants et la divulgation des fonctionnalités. Ce mouvement peut, au fil du temps, orienter un ensemble d'API vers REST ou SOAP ; une migration qu'il faut donc absolument anticiper.

Les problèmes de constitution des API peuvent détruire une application plus vite et plus radicalement que tout autre type d'erreur d'architecture.

Les architectes risquent d'être facilement échaudés s'ils se conforment à l'architecture objet et à l'infrastructure de liaison. Il est important de choisir le bon modèle d'API car les développeurs ont du mal à utiliser une interface non conforme à l'architecture des applications qu'ils mettent au point. Remarquez que les API RESTful représentent généralement des ressources, tandis que les API SOAP représentent des processus ou procédures distant(e)s.

Un protocole peut servir à lier les API à leurs utilisateurs et aux applications Web ; il s'agit en principe du tandem HTTP (Hypertext Transfer Protocol)/HTTPS. L'utilisation du protocole HTTP avec un format de données HML (Hypertext Markup Language) ou XML (eXtensible Markup Language), ou encore JSON (JavaScript Object Notation) et JavaScript sur les appareils clients, facilite la création d'interfaces utilisateur graphiques à partir d'une API. En revanche, il peut ne pas convenir lorsque l'accès au navigateur n'est pas l'objectif de l'application. Certaines applications et API peuvent utiliser un port TCP (Transmission Control Protocol) ou UDP (User Datagram Protocol) particulier au lieu du port Web 80. Ce dispositif contribue certes à séparer le trafic des API de l'activité Web, mais les conséquences au niveau du pare-feu ou de la sécurité risquent d'exiger une configuration système spéciale entraînant une exposition des API ou leur utilisation à distance.

Règles générales en matière de conception d'API

On peut considérer que la plupart des API forment une syntaxe de verbes et de noms. Par exemple, on a une phrase avec un verbe représentant une action demandée (get, put, delete) et des noms désignant les arguments qui s'appliquent à l'action. Une bonne pratique consiste à toujours générer une variable d'état/de résultat qui indique les conditions d'erreur ou la réussite de l'exécution. Les conditions d'erreur doivent être suffisamment précises pour décrire les problèmes sans ambigüité.

La sémantique de l'API, c'est-à-dire la syntaxe des fonctions fournies, est importante car la capacité de l'API à transmettre clairement ses services et paramètres évite aux développeurs de commettre des erreurs. Si l'API représente un service avec état, il est essentiel que la sémantique de la fonction soit axée sur la session (find-record, update-record, delete-record) lorsque la nature « avec état » du service est clairement établie.

Il en résulte que si, comme dans cet exemple, les fonctions update et delete portent sur l'élément de données précédemment localisé, elles ne fournissent pas leurs propres clés d'élément de données ; en effet, celles-ci seraient redondantes et risqueraient de dérouter les développeurs. En revanche, un service sans état doit systématiquement indiquer toutes les données car la session ne fournit aucun contexte.

Questions et problèmes récurrents

Les problèmes de syntaxe créés par les mises à jour ou les modifications apportées à l'API sont souvent ignorés. Chaque API présente deux faces, que le processus de changement peut désynchroniser. Pour leur API, certains architectes prévoient une variable de version afin de s'assurer que les mêmes formats soient attendus sur les deux faces. Au minimum, les côtés serveur et client d'une API doivent procéder à une validation élémentaire pour se protéger des modifications susceptibles d'induire un conflit de syntaxe, et ce afin d'éviter qu'elles contaminent les informations ou bloquent les applications.

Une autre question récurrente concerne le format des données. Le langage XML est le plus répandu pour définir les paramètres et échanger des informations ; il s'applique aux interfaces REST et SOAP. Mais le traitement XML est lourd et s'avère surtout utile pour exprimer les données sans structure. Pour l'architecture REST, JSON rencontre un succès grandissant, car il est plus facile à mettre en oeuvre et assure un typage spécifique des variables, largement utilisé et attendu dans la création d'API. Dans les cas où les API échangent des éléments de données strictement définis, il est sans doute préférable d'utiliser JSON pour les échanges RESTful.

Les tests d'API sont souvent intégrés aux processus de gestion du cycle de vie des applications. C'est justifié pour une partie d'entre eux, mais des tests unitaires spécifiques doivent également être conçus afin de valider les API et de garantir leur exécution correcte même lorsque les données contiennent des erreurs. Moins les liaisons de données et le typage d'une API sont contraignants, plus il est risqué de transmettre des informations qui entraîneront une erreur ou un blocage ultérieur. C'est pourquoi il est important d'adopter des contraintes strictes sur les variables et de tester chaque API avec un large éventail de données.

Les problèmes de constitution des API peuvent détruire une application plus vite et plus radicalement que tout autre type d'erreur d'architecture. Le temps supplémentaire passé à concevoir des API de façon à prévoir les conditions d'erreur présentes et futures sera du temps bien employé.