Version the API

[chappjc]

I've wrestled with this for a while, and it seems like using the Accept header with version in a MIME type parameter (e.g. Accept: application/json; version=1), is perhaps the "right way" to do this. The thing is, forget that and all the headaches that go with it. I want to go with version in the URL.

Much like described in this blog post: https://cloudplatform.googleblog.com/2017/06/versioning-APIs-at-Google.html

The API (not the app) should have a X.Y version where the URL contains /vX. Changes in X are thus breaking (removed or renamed fields, etc.), while changes in Y are not breaking (added fields or endpoints, etc.).

[ukane-philemon]

@chappjc, this seems to be overdue. I'd like to pick this up.

[chappjc]

OK, but there's not much to do for this, except mirror the entire /api paths on /api/v1. Obviously all /api links have to keep working.
When we make breaking changes, we'll add /api/v2.

[chappjc]

Please use Chi's routing capabilities and sub-routers as needed to avoid logic our API handler implementations where possible. Review the chi methods and consider a single Router that can be shared between the two parent paths /api and /api/vX

https://pkg.go.dev/github.com/go-chi/chi/v5#Mux.Route
https://pkg.go.dev/github.com/go-chi/chi/v5#Mux.Mount

[ukane-philemon]

we can mount the same router on different paths. on /api/ as default and /api/v{version}/.

[chappjc]

we can mount the same router on different paths. on /api/ as default and /api/v{version}/.

Right. That will probably do it.

For planning for the future, here's an interesting approach: https://github.com/go-chi/chi/tree/v5.0.8/_examples/versions
...subrouters, common handlers, and an api.version context value for handlers to modify their behavior.

Regarding the api/types package, we could consider making that it's own module (again, since it was previously), but the module version would already be at v6 since we were at v5 before we reabsorbed it into the main dcrdata module. Alternatively, we could just have subfolders like api/types/v1, which seems better for a REST API's data type versioning.

[ukane-philemon]

For planning for the future, here's an interesting approach: https://github.com/go-chi/chi/tree/v5.0.8/_examples/versions
...subrouters, common handlers, and an api.version context value for handlers to modify their behavior.

Yes, this makes sense. This will enable us to use one entry point for requests and handle them differently.

[ukane-philemon]

Alternatively, we could just have subfolders like api/types/v1, which seems better for a REST API's data type versioning.

I agree. If we want to version the api/types module, It makes sense to follow the REST API versioning too.

[ukane-philemon]

But then are these changes are included in this issue, no? Or these would be for future planning(maybe when we are about to add version 2)?