Versions and compatibility

The API carries its version in the path, /v1, and a date: that of the OpenAPI document (info.version), the day of its latest change. Every change has its entry in What’s new.

Compatible changes

They arrive in /v1 when they are ready, with their entry the same day:

• a new endpoint, a new field in a response, a new optional parameter or field in a request;
• a new value of a string the reference describes as open (like payment.method) and a new error code;
• a new permission (scope) and a new language.

So that none of them breaks your integration: ignore the fields you don’t know, treat an unknown value of an open string as a generic case, and keep a branch for the error codes you don’t handle one by one.

Vimine’s pages (sign-in, the enrolment form, the agenda) may change their look at any time; their addresses and the parameters they take follow the same rules as the API.

Changes that need action

A field removed or renamed, a parameter that becomes required, a response that changes meaning: such a change is announced at least 30 days before it lands, with an Action needed entry that says what to change and by when, and with an email to developer accounts and to whoever runs an association with an active app. When it lands, a second entry says so.

During the beta such a change lands in /v1. After the beta it will come in a new version, /v2, beside /v1 for at least six months.

The SDK and the WordPress plugin

• @vimine/sdk: while the version is 0.x, a patch (0.3.6) never asks you to change your code; a minor version (0.4.0) may, and its entry says what. The entries are also in the package, in CHANGELOG.md.
• The WordPress plugin updates from WordPress.org, where its page carries the same entries.

Following the news

• The What’s new page and its Atom feed, in every language of the portal: /en/news.xml in English, /news.xml in Italian, and so on.
• In the Vimine console, Developers shows the latest entries.
• Action needed entries also arrive by email.