API Versioning

[julianbenegas]

There are a couple of breaking changes we want to make in our own GraphQL API. The schema design is really good, but it's not perfect, and we want to improve it overtime.

But people may already rely on those imperfections, and their code depends on them. So we need to version our API.

Shopify does an interesting versioning schema, which is based on the date. Something like this: /api/2024-04/graphql. An alternative is an incremental counter, v1, v2, v3, etc, but I fear that if we get to like v43 or something, it might be weird... not sure.

To implement api versioning:

1. api.basehub.com/graphql will need to be pinned to the current version, and will not be recommended in the future.
2. api.basehub.com/<version-scheme>/graphql will be preferred instead.
3. api.basehub.com/latest/graphql will default to the latest stable version.
4. api.basehub.com/canary/graphql will default to the latest canary version.

Versioning our API will create more documentation work on our end, but I wonder what other alternatives do we have...