search

shift-org / shift-docs

Shift2Bikes: website and calendar for shift and pedalpalooza
https://shift2bikes.org
Other
22 stars 17 forks source link

API - send/receive API version as header #591

Open carrythebanner opened 8 months ago

carrythebanner commented 8 months ago

The API should include the version number as a header in responses, e.g.

API-Version: 3

(Major version number only?)

Clients would also be encouraged (though not required) to include the version they're using in requests. If the client doesn't specify, the server would assume the latest version. In the future we may rev the version and introduce breaking changes, so clients should send the version they're expecting to ensure a predictable response.

As a proof of concept for handling different versions, we could check for v1 or v2 requests and reject those. (There should be no real requests for those versions, because those version numbers were defined post-hoc well after we were already on v3.) Error status code could be 400, or possibly 406 (Not Acceptable).

ionous commented 5 months ago

with #672 and https://github.com/shift-org/shift-docs/commit/130f1f0190033ed872d97533acc2567afa33d383 sends a version number from the server with every response. configured in config.js

  api: {
    header: 'Api-Version',
    version: "3.50.0",
  },