

Ask HN: What is the 'defacto' way to version an API - olliejennings

l have been web developing for a while now, but recently l have got into purely API development.<p>The purpose of this question&#x2F;dicussion is not, how to version an API in the sense of, do you use `Version Headers` (this is my prefered option) or do you make it a url path e.g. `&#x2F;api&#x2F;v1&#x2F;resource`, but rather how to version an API within the actual code of the API.<p>I have read a lot of articles about this, many of which have given possible solutions such as:<p>1. Having route folders labeled by their version number, then manually creating routes for each of these versioned folders.
   e.g. routes&#x2F;v1&#x2F;authRoute &amp; routes&#x2F;v2&#x2F;authRoute<p>2. Defining in the route which version each route specific function is for.
   e.g. routes&#x2F;auth &amp; within auth v1: function() and v2: function<p>3. Programmatically generating the routes, based on the file structure of the routes folder
   e.g. routes&#x2F;v1&#x2F;auth and routes&#x2F;v1&#x2F;1.0&#x2F;auth would end up being &#x2F;app&#x2F;v1&#x2F;auth and app&#x2F;v1&#x2F;1.0&#x2F;auth<p>So really, l was wondering, how do companies from big to small actually managed this without requiring a lot of manual effort.
======
smt88
In my experience, different API versions come in three varieties:

1) Totally separate code bases (more common at larger companies)

2) An old branch vs. a new branch, deployed to different places

3) Separate business logic living in the same branch of the same code base

Which form the company takes is usually just circumstance. It sounds like you
want to talk about #3.

If you're on version 1 of the API and don't have concrete plans for a version
2, _don 't worry about it_. "Pre-optimization is the root of all evil" after
all. Cross that bridge when you come to it.

How it could actually work in your code depends a lot on the architecture of
the code, as well as the language. The solution you choose should consider
your resources, as well.

Personally, I've had a lot of issues sharing code between an old API and a new
one, even though it sounds like a great idea. The problem is that you have to
run unit tests every single time you want to add or change a method on your
models. Either that, or you end up adding tons of methods to your models to
avoid breakage, and then you have a huge maintenance problem.

So my suggestion would be #2.

~~~
opless
Totally agree with the #2 conclusion.

