REST API BEST PRACTISES #2

Stop Messing Up Your API Versions!

If you’re using /v1/products and /v2/products, this article is for you

Love my content? Keep me fueled with a coffee! ☕ Buy Me a Coffee

If you are not a medium member, Read it here.
Dear Folks, Your 50 claps 👏👏 help the discussion [article] reach more developers 👀 on Medium, and your comments 💬 make me to keep writing. Dont forget to checkout the responses💬 from other developers.

Recently, I got the requirement to update my API to a new version, also the old version running to support existing clients.

My original endpoint was /products.

So, I thought:

Let's switch to /v1/products the current version and /v2/products the new one. Simple, right?

GET /v1/products
GET /v2/products

This approach feels “yeah thats the way”,

BUT

It violates REST principles and creates maintaince hell.

Simpilicity Trap

@RestController  
@RequestMapping("/v1/products")  
public class ProductControllerV1 { ... }  

@RestController  
@RequestMapping("/v2/products")  
public class ProductControllerV2 { ... }  

Yeah, it's Quick to implement right? Hmm… but, we have two controllers (and tests, docs…) to maintain.

Tutorials and legacy systems normalize URL versioning. If we check for versioning in Google, URL API versioning will be there from many sources.

Why Versioning in URLs Breaks REST?

URIs Should Be Timeless

REST mentioned that URIs are stable identifiers for resources. When we version URLs:

• Clients hardcode paths like /v1/products, creating tight coupling.
• Changing a URI is like changing a book’s ISBN — it breaks every library that references it.

It is not easy for Maintenance