3 clés pour réussir le développement d’API

Avoir la bonne sémantique

La chose la plus importante est d’avoir la bonne sémantique. Si cela peut sembler vague d’un premier abord, il s’agit surtout d’identifier le bon nommage, les bons paramètres, la structure des données ainsi passées, l’usage des headers HTTP et les conventions qui entourent tout cela. Toutefois, les principes de base des interfaces REST sont souvent sujets à l’interprétation qu’en font les designers. Et de fait, la qualité de ces interprétations finit par être très subjective. Cela est particulièrement vrai pour le nommage des endpoints et pour l’usage des paramètres et des structures de données.

Le nom de ces endpoints représente la partie la plus visible d’une API et transmet davantage d’informations sur la conception que n’importe quelle autre fonction. Que cet endpoint soit appelé en fonction de la ressource, d’un processus ou d’un medium, l’API sera bien mieux comprise si la convention est appliquée de façon cohérente. Dans une grande entreprise, la seule façon d’atteindre ce niveau de cohérence est de mettre en place des conventions et de le faire appliquer par toutes les équipes de développement. Cela demande certes un grand effort en matière de management, presqu’autant que celui consenti dans le développement.

Puis surviennent les problèmes liés au nommage des paramètres et des structures de données. Les interfaces ont toutes des besoins différents en matière de données. Là encore les conventions sont utiles. Si le nommage est « UneAPIFaitCela » et « UneAutreFaitCela », ensemble, les API sont moins compréhensibles. La même chose s’applique également aux paramètres et aux structures de données. En la matière, NetFlix et Twitter offrent plusieurs exemples probants.

Découverte et documentation

Même si la conception de vos API est bonne et que les conventions sont appliquées de façon cohérente, vos développements ne seront que peu utiles s’ils ne sont pas accompagnés d’un guide des fonctions et d’un moyen pour explorer les différents endpoints. Heureusement, nous avons Swagger, un outil pour développer et tester les API.

Swagger est en fait une spécification qui permet de décrire une API RESTful de façon structurée, via JSON ou YAML, comme langages de description. Autour de cette spécification, on retrouve un ensemble d’outils pour contrôler les marqueurs et générer une documentation HTML.

L’un des points clé de Swagger est la validation du modèle. Lors du processus de documentation d’une API, vous définissez les structures de données retournées par les endpoints. Vous pouvez documenter les champs, qu’ils soient obligatoires ou optionnels, ainsi que les plages de valeur et les contraintes. Vous pouvez également vous appuyer sur certaines bibliothèques pour valider les données entrantes lors du runtime, et retourner des informations sur les erreurs générées si la validation échoue. Cela permet d’économiser du temps et de s’assurer que le code fonctionne à l’entrée.

Accès et tests

L’un des premiers obstacles rencontrés lorsqu’on démarre avec une API est de comprendre son fonctionnement. Aussi bien décrite et formée soit-elle, l’ API doit être testée dès le début du processus de développement. L’un des outils clé dans ce domaine est Postman, une extension au navigateur Chrome. Postman permet de définir des collections d’endpoints, avec les URL, des paramètres, les headers et les données qui doivent être exécutés. Une fois défini, un endpoint peut être exécuté en un seul clic et les performances de l’appel évaluées.

Il existe beaucoup d’éléments à prendre en  compte dans le développement d’API. L’un des plus structurants porte sur le contrôle de version. Mais en suivant les méthodes listées dans cet article, vous pourrez créer des API adaptées, visibles et pouvant être facilement testées. Au final, cela vous permettra d’éviter le chaos en matière de gestion d’API.