Versions et compatibilité

L’API porte sa version dans le chemin, /v1, et une date : celle du document OpenAPI (info.version), le jour de sa dernière modification. Chaque modification a son entrée dans les Nouveautés.

Les modifications compatibles

Elles arrivent dans /v1 quand elles sont prêtes, avec leur entrée le jour même :

• un nouvel endpoint, un nouveau champ dans une réponse, un nouveau paramètre ou champ facultatif dans une requête ;
• une nouvelle valeur d’une chaîne que la référence décrit comme ouverte (comme payment.method) et un nouveau code d’erreur ;
• une nouvelle autorisation (scope) et une nouvelle langue.

Pour qu’aucune ne casse votre intégration : ignorez les champs que vous ne connaissez pas, traitez une valeur inconnue d’une chaîne ouverte comme un cas générique, et prévoyez une branche pour les code d’erreur que vous ne traitez pas un par un.

Les pages de Vimine (la connexion, le formulaire d’adhésion, l’agenda) peuvent changer d’apparence à tout moment ; leurs adresses et les paramètres qu’elles acceptent suivent les mêmes règles que l’API.

Les modifications qui demandent une action

Un champ retiré ou renommé, un paramètre qui devient obligatoire, une réponse qui change de sens : une telle modification est annoncée au moins 30 jours avant d’arriver, par une entrée Action requise qui dit quoi changer et pour quand, et par un e-mail aux comptes développeur et à qui dirige une association avec une application active. Quand elle arrive, une seconde entrée le dit.

Pendant la bêta, une telle modification arrive dans /v1. Après la bêta, elle arrivera dans une nouvelle version, /v2, à côté de /v1 pendant au moins six mois.

Le SDK et le plugin WordPress

• @vimine/sdk : tant que la version est en 0.x, un correctif (0.3.6) ne vous demande jamais de changer votre code ; une version mineure (0.4.0) peut le faire, et son entrée dit quoi. Les entrées sont aussi dans le paquet, dans CHANGELOG.md.
• Le plugin WordPress se met à jour depuis WordPress.org, où sa fiche reprend les mêmes entrées.

Suivre les nouveautés

• La page Nouveautés et son flux Atom, dans chaque langue du portail : /fr/news.xml en français, /news.xml en italien, et ainsi de suite.
• Dans la console de Vimine, Développeurs affiche les dernières entrées.
• Les entrées Action requise arrivent aussi par e-mail.