
API design: Which version of versioning is right for you? - moks
https://cloud.google.com/blog/products/gcp/api-design-which-version-of-versioning-is-right-for-you
======
jmartrican
One issue I see with HTTP header versioning, is that now I have to add the
HTTP version header into my routing logic. I already have to take domain, sub-
domain, protocol, HTTP-verb, application context, and path into account when
considering routing of HTTP requests. When defining my API signature, I would
now need to include more than just the URL path and verb, I would need to
include the version header value. I can imagine troubleshooting with other
engineers.. "wait can you look through the logs and verify the http version
header you used for that request."

Also, I really like when one piece of data can serve dual purpose use. In this
case, the URL, which is highly visible, contains the version in it. So the one
string of data reveals more information to me.

~~~
segmondy

       func metrics(w http.ResponseWriter, r *http.Request) {
       }
       func AddV1Routes(r *mux.Router) {
        r.HandleFunc("/metrics/", metrics).Methods("GET")
        r.HandleFunc("/v1func/", v1func).Methods("GET")
       }
       func AddV2Routes(r *mux.Router) {
        r.HandleFunc("/metrics/", metrics).Methods("GET")
        r.HandleFunc("/v2func/", v1func).Methods("GET")
       }
    
    
      r := mux.NewRouter()
      AddV1Routes(r.PathPrefix("/api/v1").Subrouter())
      AddV2Routes(r.PathPrefix("/api/v2").Subrouter())
      handler := c.Handler(r)
      http.ListenAndServe(":5000", handler
    

With a pattern like this, you can just decide which functions to group by
version.

~~~
dariusj18
Or, you could just deploy a copy of each version of the code using a reverse
proxy.

------
justicezyx
So many texts no one line of example? I am totally confused...

~~~
dlkinney
His talk at Google Next 18 was much more clear:

[https://www.youtube.com/watch?v=P0a7PwRNLVU](https://www.youtube.com/watch?v=P0a7PwRNLVU)

It might feel a bit aimless at first, but he pulls it together about halfway
through. By the end makes good, insightful points. Definitely worth the watch.

------
catlifeonmars
A lot of the problems related to organization of entities and type description
can be solved by using out-of-band type metadata (i.e. GraphQL). It’s not a
panacea by any means, and may not be the right fit for many APIs, but I’m
surprised it wasn’t mentioned at all, considering that the article is about
API design.

------
wellpast
Or no versioning.

Create new endpoint URIs for new semantics.

Use vocabulary-based (property-based) entities and never change word
(property) semantics.

Contrary to its unpopularity (or _because_ of?), this “strategy”* is far far
simpler to maintain and evolve than is “versioning”.

*I say “strategy” because this is more commonsense: it’s how we do things in the real world anyway.

~~~
braindeath
I think this is still versioning. You just end up versioning with the endpoint
URI. Eg many names that end -2 or -3.

~~~
wellpast
If the semantics change, why do you need a “-2”?

If the semantics don’t change, why do you need a new URI.

Keep in mind you don’t have to focus on the suffix or the last part of the
path name when you are naming things by URI.

Also, why is it versioning? You have two endpoints in use. One happened to
exist before the other one. That’s an incidental property. And there are
scenarios where you may deprecate the latter before the former.

Thinking in “versions” is not an accurate/ergonomic mapping of the domain
anyway; we’ve just been tricked into thinking that way because... anthropology
something.

~~~
antonvs
> If the semantics change, why do you need a “-2”?

Because the API may serve the same purpose as the original, with some modified
semantics.

> Also, why is it versioning?

Because the API may serve the same purpose as the original, with some modified
semantics.

Sharing a common name with versioning helps identify the relationships between
the versions. It also avoids polluting the API namespace with a set of
different names for different versions of essentially the same operations.

> Thinking in “versions” is not an accurate/ergonomic mapping of the domain
> anyway; we’ve just been tricked into thinking that way because...
> anthropology something.

It feels to me like you're trying to hard to be contrarian, or perhaps you're
dealing with some special case scenario where your strategy makes sense.

You'd need to explain the argument in significantly more detail to have a
chance of making it convincing.

~~~
wellpast
See the link to Rich Hickey’s talk in my other comment. It covers the issues
pretty well.

I’m not being contrarian, but I am expressing frustration with a common yet
unnecessarily complicated approach to a general problem. But I stand by my
statements, they’ve paid off tremendously in real world contexts.

------
awkim
Google's great at fast tracking APIs to their end of life.

