[API] Inform about API modifications

[urien]

Comment informer les utilisateurs des apis lors qu'une modification intervient ? Peut-être avec la mise en place d'une clé d'API associée à un mel auquel on adresse des messages ? A priori le nombre des applications faisant un usage, en production, de nos apis va augmenter significativement.

[Clm-Roig]

La difficulté va être surtout d'un point de vue "communication" et "présentation" des modifications je pense : que devons-nous communiquer précisément ? Qui fait ce travail là ?

En tant que développeur, on documente notre travail via les commits que je référence ensuite dans les notes de releases (exemple ici). On a aussi les Pull Requests sur lesquelles on ajoute pas mal de détails techniques.

Mais ces choses-là ne sont pas très présentables ni très agréables à lire... Il y aurait une vraie réflexion à mener je pense, quitte à demander aux utilisateurs de l'API ce qu'ils attendent de nous précisément :slightly_smiling_face:

[urien]

J'écris quelques mots pour amorcer la discussion

Google adresse un message aux utilisateurs de ses apis pour prévenir quand elles disparaissent, quand il faut passer à une nouvelle version... quand la tarification change. Avec une échéance à 6 mois, 1 mois... Dans l'idéal il faudrait que les apis s'enrichissent mais que les routes que l'on met en place ne disparaissent pas même si elles sont dépréciées. Pour une version d'api il suffit de garder une documentation à jour comme le service swagger que l'on a. On peut créer une liste de diffusion (api@grottocenter.org) qui permet aux abonnés d'avoir des infos quand il y a des ruptures dans le fonctionnement des apis (changement d'url, changement de version,...). Dans un second temps on pourrait avoir une inscription automatique sur cette liste pour les personnes qui demandent une clé d'api Je vais proposer à Juliette de préciser ici ce que pourraient être ses besoins

[juliettefabre]

Mon retour : il m'est arrivé plusieurs fois de réaliser au bout d'un moment que le code JS qui utilise l'API Grotto plantait, suite à des modifs de l'API :

• cas 1 : modification de l'URL de l'API (il me semble que c'est arrivé 2 fois ?)
• cas 2 : modification du nom d'une méthode (il me semble que c'est arrivé avec la méthode entrances)
• cas 3 : modification de la structure du résultat d'une méthode (exemple avec l'id du massif qui est désormais renvoyé dans un champ [id])

Ce qu'il faudrait d'après moi c'est éviter que les services liés à l'API plantent du jour au lendemain :

• informer avant une nouvelle version majeure
• maintenir la version précédente un certain temps

[Clm-Roig]

Merci pour ce retour précieux. Le cas 1 ne devrait plus se reproduire. L'URL api.grottocenter.org ne bougera plus et nous permettra plus de flexibilité de notre côté en choisissant vers quoi elle doit pointer. Le cas 2 était exceptionnel et résultait d'une mauvaise traduction (entrée pouvant se traduire entry et entrance en anglais).

Concernant le cas 3, c'est noté. Il arrive que l'on complète des données pour lesquelles précédemment on ne renvoyait qu'un id (ce qui est arrivé pour les massifs par exemple).

On va réfléchir à tout ça pour éviter que ça ne se reproduise, merci encore !

[Clm-Roig]

J'ai commencé à marquer quelques routes comme "deprecated" dans le fichier routes.js trouvable ici : https://github.com/GrottoCenter/Grottocenter3/blob/develop/config/routes.js Une alternative est proposée pour chaque route : aucune fonctionnalité ne disparaîtra, c'est juste des changements de nomenclature pour le moment (entry => entrance, cave => network (dans certains cas) etc.).

Je pense qu'il serait judicieux, à moyen / long terme, de supprimer ces routes dépréciées. Reste à définir au bout de combien de temps...