Good practice regarding URLs and version upgrades

[AntoineAugusti]

Hello,

We're wondering about the recommended practice regarding GBFS versions in the URL and version upgrades.

Imagine you have example.com/gbfs/gbfs.json at 3.0 with gbfs_versions containing links to other versions (such as example.com/gbfs/2.3/gbfs.json).

You now upgrade your main GBFS version to 3.1. Reusers can be surprised by your move and it now breaks their app.

• Should example.com/gbfs/gbfs.json switch to 3.1 silently?
• Should producers always include the version in the URL (and avoid URLs like example.com/gbfs/gbfs.json)
• Should producers have URLs like example.com/gbfs/latest/gbfs.json which can lead to silent version upgrades

[testower]

At Entur, we use major versions in URLs. We do minor upgrades on those safely because they are non-breaking and therefore should be backwards compatible.

[richfab]

As an additional use-case, Deutsche Bahn recently decided that they won’t represent the minor Version in the URL.

So for Deutsche Bahn, the URL for a v2.3 GBFS feed is: /apis/shared-mobility-gbfs/v2/de.

Curious to hear inputs from other producers and consumers.

[Yaronn44]

At Ecovelo, we have a distinct URL for each major and minor version (v2.2, v2.3, v3.0, etc.), but we have also deployed a unique URL without a version number. It is possible to specify a particular version by using the version header. This solution is a bit more discreet and unconventional, but there is only one URL to manage.

In any case, as a consumer, I think it's better to set the version you're using, either via the URL or via the header (with the solution I'm proposing).