If you are anything like me, or tens of thousands of others working in the web development domain, you know what the title means. We are going to talk about the widely debated “v” in API endpoints.

Do I like it? Well, obviously not. I’ll tell you why.

1. It’s ugly!

It makes reading documentations very difficult, because you’ll need to version your document as well. And you’ll have to make sure you are using the latest document, or the document that’s relevant to the version of API you are consuming. Wouldn’t it be a lot easier if you had one version of API and one version of documentation?

I know what people over at the other camp are shouting — your APIs will change and you need to have versions. I agree, and I’ll tell you how I prefer to handle those changes later.

2. If you update your API version with such endpoints, clients that are not updated will break.

Nobody likes this, right? If a few clients consuming your APIs are broken, you are losing those many customers. How is that good news? Plus, it’s a pain in the ass for developers to update their code whenever you update your endpoints.

I know, you basically have to change the value of one variable/constant in the codebase. But does that justify changing all your endpoints?

How I prefer to handle changes

It’s obvious that you update your APIs. Some APIs get deprecated and some get added in each version of your API service. You might even have to change an existing API — add/remove parameters. This is when you do an API update which leads to a change in the endpoint, the “v” part at least.

But in my approach, or in what I propose, the endpoints don’t change. Say for example you have the following API:

/user/v1.0/login

and it takes the following parameters:

String username mandatory
String password mandatory

Now, you decided you want to drop the extra ‘username’ field in your schema and use the email field instead. So your new endpoint looks like this:

/user/v1.1/login

with parameters:

String email mandatory
String password mandatory

For this change, you’d have two different versions of documentation. And if your clients did not update themselves after the time you gave them before deprecating the old version, they break. Instead, why not this:

Before

/user/login
String username mandatory
String password mandatory

After

/user/login
String username
String email
String password mandatory
Either username or email must be provided.

This way, you have backward compatibility. Your clients will not break. I agree that this is a different version and you need to update the documentation as well.

Of course, you can’t have this backward compatibility in all cases and you’ll need to update some API in a way that would certainly break the clients if they don’t update, but that would be only for certain endpoints, not all.

Even if the clients break, they would be getting a proper error message from your API service, they won’t be hitting a 404. This means even your users will get the appropriate reason for the failure.

I know this isn’t the best approach or the approach that most people would agree with. But if you want to show me a better way, or have a strong point as to why using the “version-in-endpoints approach” is the absolute right way, please comment. I’m all eyes and ears, and would love to learn better ways of approaching this.