Versioning

Our API is versioned to allow us to continually update our system while providing third-party developers with ways to implement new features and deprecate code in a clear manner.

Once importants changes are made, a new version is deployed to fix all our internals APIs in this state and from this, new developpements are made for the futur version, without modifying the old ones.

Release Schedule

There is currently no specific recurrence for the release of new versions. However, we try to release a new version every few months as new features are developed.

Calling specific version

By default the version used by all your calls will be the one defined with your account and your API key.

curl -X GET "https://api.maas.ecovelo.mobi/vehicules" -H  "accept: application/json"

However, it is possible to call a specific version directly if you decide to do so by passing it in the url (here version 2021-05-06):

Warning

If you set the version explicitly, this version must be more recent than you default version, otherwise an error will trigger.

curl -X GET "https://api.maas.ecovelo.mobi/2021-05-06/vehicules" -H  "accept: application/json"

We still recommend that you update to the latest versions as often as possible by setting it as your default version in your account.

Setting the version explicitly may be useful for testing a new version in preparation for an upgrade, but is not recommended for global use in your application as it may lead to unwanted error if an exclicitly used version is deprecated.

The response header of all calls will contains the header x-ecovelo-api-version, which is the version that was used to execute the request. It allow you to see which version your application is using.

Deprecation

Versions will be deprecated if it become outdated, unsafe or unnecessary. Once deprecated, the version is removed, and calling it will either trigger an error if call explicitly, or redirect your call to the new oldest version if used as the default version.

One a version is out, it will be deprecated at most a year later. An email will be send to warn third-party integration still using it to force them using a more recent version in their application.