Une API doit être centrée sur la donnée
Une API est idéalement centrée sur la donnée au travers de ressources alignées sur le modèle standardisé « mondial » ou « corporate » de la donnée condition de sa lisibilité et de son usage facilité.
Réaliser des ressources optimisées et universelles :
L’exposition d’APIs, qu’il s’agisse de services internes, dédiés partenaires, monétisables ou pas auprès des clients et encore plus dans le cas des API ouvertes (Open API), la rigueur d’écriture des ressources et la sémantique, la morphologie de la donnée est capitale.
Dans certains métiers, des modèles ontologiques existent issus de consortiums, par exemple BIAN ou la DSP2 d’Open Banking pour le domaine bancaire, eTom dans les télécoms, NAF pour l’OTAN ou du moins un format standardisé des données avec GS1 ou les standards ISO.
Cette adhésion évite des traductions d’objets, de propriétés, de valeurs discrètes ou de noms d’associations, de relations entre concepts hasardeux qui deviennent largement compréhensibles par les métiers car un catalogue, un portail d’API expose idéalement la documentation issue du swagger maintenant « OpenAPI Specification ».
Il est ainsi idéal de modéliser, en parallèle, un dictionnaire de données, fixant le nom des termes, des attributs, des relations des éléments étant nécessaires pour réaliser des ressources optimisées et universelles. Ce modèle est valable pour les bases de données, les datamarts, le format et les schémas des messages événementiels (KAFKA).
Importance des guidelines ou RefCards :
Les guidelines ou RefCards de l’entreprise préciseront les règles de design des endpoints des API :
- Interdiction d’utiliser une propriété non identifiante dans un chemin
- Unicité de l’identifiant d’un objet (code barre à 13 caractères GTIN, de GS1 précité, d’un produit de la grande distribution et non l’identifiant interne de la grande enseigne …)
- Profondeur de navigation entre les concepts constituant les ressources (pas plus de trois en « profondeur »)
- L’interdiction de redéfinir un schéma de données sur un objet secondaire de l’API, extensible sur l’objet ou les objets principaux de l’API (idéalement mono-concept …).
Cet asset de l’entreprise, l’API, est un produit avec son cycle de vie propre. Il est une vitrine à l’exemple de celles des sociétés de transports aériens qui ont très tôt exposé des API extrêmement bien documentées sur leurs portails car il était vital pour elles d’être consommées par les plateformes de réservation, des moteurs de recherche thématiques type KAYAK, TRIVAGO ou encore TRIPADVISOR …
Ceci est extensible sur n’importe quelle industrie, service marchand ou pas, activité tertiaire …
Et vous dans votre domaine, un standard auquel adhérer, une maturité de l‘ontologie de vos données dans un spectre transverse bien plus large que celui des APIs ?
Des questions ? Un projet ?