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

#1

Post by olliejennings » Thu, Mar 12, 2015, 10:00 AM UTC

l have been web developing for a while now, but recently l have got into purely API development.

The purpose of this question/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. `/api/v1/resource`, but rather how to version an API within the actual code of the API.

I have read a lot of articles about this, many of which have given possible solutions such as:

1. Having route folders labeled by their version number, then manually creating routes for each of these versioned folders. e.g. routes/v1/authRoute & routes/v2/authRoute

2. Defining in the route which version each route specific function is for. e.g. routes/auth & within auth v1: function() and v2: function

3. Programmatically generating the routes, based on the file structure of the routes folder e.g. routes/v1/auth and routes/v1/1.0/auth would end up being /app/v1/auth and app/v1/1.0/auth

So really, l was wondering, how do companies from big to small actually managed this without requiring a lot of manual effort.

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

#2

Post by smt88 » Thu, Mar 12, 2015, 10:10 AM UTC

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.

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

#3

Post by opless » Thu, Mar 12, 2015, 11:23 AM UTC

smt88 wrote: post #2

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…

Totally agree with the #2 conclusion.