Cosmos-sdk: Version REST API

[faboweb]

Summary

To be able to later migrate the API easily we should prefix all endpoints. This is an easy fix right now and should save us a bunch of work later.

Example:

• Now GET /keys
• Prefixed GET /v1/keys

Problem Definition

Proposal

---

For Admin Use

• [ ] Not duplicate issue
• [ ] Appropriate labels applied
• [ ] Appropriate contributors tagged
• [ ] Contributor assigned/self-assigned

[fedekunze]

++

Useful resources:

• https://tyk.io/blog/when-and-how-do-you-version-your-api/
• https://restfulapi.net/versioning/

[alexanderbez]

Mhmmm how will REST API versions correlate to the SDK. I.e. what version of the SDK can line up with what version of an API?

[faboweb]

The API version doesn't match the SDK version. It will always be v1 until we introduce a v2 which will/should run in parallel to v1 until v1 is removed. Versioning the API helps apps to slowly migrate. Voyager i.e. would run on v1. If braking changes are introduced, Voyager can quickly move to v2 to benefit from an improved feature set, where other products like let's say the explorer still run on v1 because migrating them is less of a priority.

[fedekunze]

It's also good for users to keep track of changes in the API. We could have docs for each one of the API versions so that devs don't have to open new issues to ask for the correct endpoint

[faboweb]

And it is a really small change: Just add /v1 in front of all request handlers.

[ValarDragon]

cc @ebuchman should the versioning ADR account for RPC?

[jackzampolin]

I think this is a GREAT idea. Can we call this proposal accepted? cc @ebuchman, @faboweb, @fedekunze ?

[fedekunze]

How to think about version numbers in a pragmatic way with REST?
Never release an API without a version. Make the version mandatory.
Specify the version with a 'v' prefix. Move it all the way to the left in the URL so that it has
the highest scope (e.g. /v1/dogs).
Use a simple ordinal number. Don't use the dot notation like v1.2 because it implies a
granularity of versioning that doesn't work well with APIs--it's an interface not an
implementation. Stick with v1, v2, and so on.
How many versions should you maintain? Maintain at least one version back.
For how long should you maintain a version? Give developers at least one cycle to react
before obsoleting a version.
Sometimes that's 6 months; sometimes it’s 2 years. It depends on your developers'
development platform, application type, and application users. For example, mobile apps
take longer to rev’ than Web apps.

Source: API Design eBook page 14

[jackzampolin]

Took a couple of minutes looking at this. I think the right way to go here is to expose a RestServer.V1Router and RestServer.V2Router functions:

func (rs *RestServer) V1Router() *mux.Router {
    return rs.Mux.PathPrefix("/v1").Subrouter()
}

This way when registering routes in the module you can utilize both prefixes if needed (below example is Auth):

// register REST routes
func RegisterRoutes(cliCtx context.CLIContext, r *mux.Router, cdc *codec.Codec, storeName string) {
    r.V1Router().HandleFunc(
        "/auth/accounts/{address}",
        QueryAccountRequestHandlerFn(storeName, cdc, context.GetAccountDecoder(cdc), cliCtx),
    ).Methods("GET")
    r.V1Router().HandleFunc(
        "/bank/balances/{address}",
        QueryBalancesRequestHandlerFn(storeName, cdc, context.GetAccountDecoder(cdc), cliCtx),
    ).Methods("GET")
    r.V1Router().HandleFunc(
        "/tx/sign",
        SignTxRequestHandlerFn(cdc, cliCtx),
    ).Methods("POST")
}

Thoughts? @fedekunze @faboweb @alexanderbez @ValarDragon