DEV Community

Roshan singh
Roshan singh

Posted on

What is API Versioning?

#webdev #backenddevelopment #api #programming

🚀 What is API Versioning? (Beginner Friendly)

If you're learning backend development, you've probably seen APIs like these:

GET /api/v1/users
GET /api/v2/users
Enter fullscreen mode Exit fullscreen mode

The first question most beginners ask is:

Why do we need v1, v2, or v3? Why not just update the existing API?

Let's understand it with a simple example.

📖 What is API Versioning?

API Versioning is a way to make changes to an API without breaking applications that are already using it.

Instead of changing the existing API, developers create a new version.

🧑‍💻 Example

Suppose you have an API like this.

Version 1

Request

GET /api/v1/user
Enter fullscreen mode Exit fullscreen mode

Response

{
  "name": "Roshan",
  "age": 22
}
Enter fullscreen mode Exit fullscreen mode

Everything works perfectly.

🤔 A Few Months Later...

Your company decides that age should no longer be public.

Your first thought might be:

Why not just remove age from Version 1?

Because thousands of applications might already be using this API.

For example, an old mobile app expects this response:

{
  "name": "Roshan",
  "age": 22
}
Enter fullscreen mode Exit fullscreen mode

If you suddenly change the API to this:

{
  "name": "Roshan"
}
Enter fullscreen mode Exit fullscreen mode

the old app may stop working because it was expecting the age field.

✅ The Solution: Create a New Version

Instead of modifying v1, create v2.

Version 2

Request

GET /api/v2/user
Enter fullscreen mode Exit fullscreen mode

Response

{
  "name": "Roshan"
}
Enter fullscreen mode Exit fullscreen mode

Now both versions exist.

/api/v1/user  → Returns name + age
/api/v2/user  → Returns only name
Enter fullscreen mode Exit fullscreen mode

This means:

  • ✅ Old applications continue using v1
  • ✅ New applications use v2
  • ✅ Nothing breaks

❓But Won't Old Users Keep Using v1 Forever?

No.

Here's what usually happens.

Step 1

The old version of your app calls:

GET /api/v1/user
Enter fullscreen mode Exit fullscreen mode

Step 2

You release a new version of your app.

Inside the new app, you change the API call to:

GET /api/v2/user
Enter fullscreen mode Exit fullscreen mode

Step 3

Users update the app from the Play Store or App Store.

After updating, the app automatically starts using v2.

Users don't need to change anything manually.

👴 What About Users Who Never Update?

For some time, they continue using v1.

That's why companies keep older API versions running.

A typical lifecycle looks like this:

Release v1
      │
      ▼
Users start using it
      │
      ▼
Release v2
      │
      ▼
New app uses v2
      │
      ▼
Most users update
      │
      ▼
Announce v1 is deprecated
      │
      ▼
Remove v1
Enter fullscreen mode Exit fullscreen mode

Keeping an old version for some time before removing it is called API Deprecation.

🎯 Why is API Versioning Important?

  • Prevents existing applications from breaking.
  • Allows developers to improve the API safely.
  • Gives users time to update their applications.
  • Makes it easier to add new features in the future.

📝 Final Thoughts

Think of API versions like software versions.

  • v1 → Old version
  • v2 → Improved version
  • v3 → Latest version

Older applications continue using the version they were built for, while newer applications use the latest version.

That's why you'll often see APIs like:

GET /api/v1/users
GET /api/v2/users
GET /api/v3/users
Enter fullscreen mode Exit fullscreen mode

API Versioning allows your API to evolve without breaking existing applications.

Top comments (0)