Versioni e compatibilità

L’API ha la versione nel percorso, /v1, e una data: quella del documento OpenAPI (info.version), il giorno della sua ultima modifica. Ogni modifica ha la sua voce nelle Novità.

Le modifiche compatibili

Arrivano in /v1 quando sono pronte, con la loro voce lo stesso giorno:

• un nuovo endpoint, un nuovo campo in una risposta, un nuovo parametro o campo facoltativo in una richiesta;
• un nuovo valore di una stringa che il riferimento descrive come aperta (come payment.method) e un nuovo code di errore;
• un nuovo permesso (scope) e una nuova lingua.

Perché nessuna rompa la tua integrazione: ignora i campi che non conosci, tratta un valore sconosciuto di una stringa aperta come un caso generico, e prevedi un ramo per i code di errore che non gestisci uno per uno.

Le pagine di Vimine (l’accesso, il modulo di adesione, l’agenda) possono cambiare aspetto in ogni momento; i loro indirizzi e i parametri che accettano seguono le stesse regole dell’API.

Le modifiche che chiedono un intervento

Un campo tolto o rinominato, un parametro che diventa obbligatorio, una risposta che cambia significato: una modifica così è annunciata almeno 30 giorni prima di arrivare, con una voce Azione richiesta che dice cosa cambiare ed entro quando, e con una mail a chi ha un account sviluppatore e a chi guida un’associazione con un’app attiva. Quando arriva, una seconda voce lo dice.

Durante la beta una modifica così arriva in /v1. Dopo la beta arriverà in una nuova versione, /v2, accanto a /v1 per almeno sei mesi.

L’SDK e il plugin WordPress

• @vimine/sdk: finché la versione è 0.x, una patch (0.3.6) non chiede mai di cambiare il tuo codice; una versione minore (0.4.0) può farlo, e la sua voce dice cosa. Le voci sono anche nel pacchetto, in CHANGELOG.md.
• Il plugin WordPress si aggiorna da WordPress.org, dove la sua scheda riporta le stesse voci.

Seguire le novità

• La pagina Novità e il suo feed Atom, in ogni lingua del portale: /news.xml in italiano, /en/news.xml in inglese, e così via.
• Nella console di Vimine, Sviluppatori mostra le ultime voci.
• Le voci Azione richiesta arrivano anche per mail.