API design: Which version of versioning is right for you?

https://cloud.google.com/blog/products/gcp/api-design-which-version-of-versioning-is-right-for-you

by moks • 7 years ago

51 15 7 years ago

cloud.google.com

justicezyx• 7 years ago

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

dlkinney• 7 years ago

His talk at Google Next 18 was much more clear:

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.

awkim• 7 years ago

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

jmartrican• 7 years ago

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• 7 years ago

   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• 7 years ago

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

wellpast4• 7 years ago

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• 7 years ago

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

wellpast4• 7 years ago

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.

chrisweekly2• 7 years ago

Could you please give an example of these property-based entities, or link to an API that follows this approach? I think I understand your suggestion but want to be sure. New endpoints for new semantics seems rock-solid to me along same lines as content-addressable / immutable build artifacts which I endorse.

wellpast4• 7 years ago

Rich Hickey explains a similar thinking in this talk https://youtu.be/oyLBGkS5ICk but it’s more directed at code libraries. The same arguments apply.

I 100% think this is the way to go for internal APIs.

For public APIs I may change my opinion here for more sociological/political reasons. The rational/technical reasons all still remain.

catlifeonmars• 7 years ago

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.

API design: Which version of versioning is right for you?

Related Stories