MobilityData
Good practice regarding URLs and version upgrades
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.jsonswitch 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.jsonwhich can lead to silent version upgrades
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.
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.
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).
This discussion has been automatically marked as stale because it has not had recent activity. It will be closed in 30 days if no further activity occurs. Thank you for your contributions.
It seems that we have a consensus. I propose to add this as a good practice to the spec:
The URL SHOULD contain the MAJOR version number. If upgrading to a MINOR version, the URL SHOULD NOT change. eg:
example.com/gbfs/v3/gbfs.json