

How to do API Versioning? - Geetha

I have a query in my usecase. Please help me to solve.<p>This is my scenario :<p>I have to do API versioning. I am using REST APIs with Restlet framework. I am confused how to implement the versioning in Java Source code.<p>If my API looks like this : http:&#x2F;&#x2F;localhost:8080&#x2F;example.com&#x2F;v2&#x2F;hello
Then In my source code how to map the version with appropriate functionality?<p>For example :<p>If(version == 1) {&#x2F;&#x2F;Do Version 1 Source Code}
else If(version == 2) {&#x2F;&#x2F;Do Version 2 Source Code}
else If(version == 3) {&#x2F;&#x2F;Do Version 3 Source Code} ………..<p>If I did like this, Then why we are going for Versioning. We can implement Manually Right? And also If I have to add some 100 versions, then the code looks uglier and it becomes lengthier.
I get confused how to map in Source Code. Please Clarify my doubt.<p>I have read that we can use annotations for handling API versioning. But I don&#x27;t know what are the annotations available in restlet framework. Please let me know.<p>Regards,
Geetha.
======
hawleyal
One option is to implement the version number as the context root of the app.
Then you just leave v1 app running while you code and release v2 app. This
allows complete isolation, but may be harder to manage if you have
architecture/security changes and want to upgrade v1.

Another approach I have seen is just providing backwards compatibility where
it matters or where there are changes. This would be similar to how a library
works. You try to limit things that need to do if-def on version number.
Usually only 2 versions are maintained simultaneously. v2 still supports the
requests of v1, but when v3 is released v1 features are gone.

I am sure there are other methods.

Edit:
[https://www.google.com/search?q=stackoverflow+api+versioning](https://www.google.com/search?q=stackoverflow+api+versioning)

------
jlouvel
Restlet team has answered in this GitHub issue:
[https://github.com/restlet/restlet-framework-
java/issues/105...](https://github.com/restlet/restlet-framework-
java/issues/1056)

------
davismwfl
I can't answer specifically with java and the restlet framework. But in
general, a mistake I have seen over and over again is developers thinking
version of software. When you are building an API you are versioning the
communication contract, not the software. You may completely change the
implementation but as long as the contract doesn't change it is fine, this
also means you can add optional fields to an existing contract without
breaking the contract. Also, this is why you should spend a lot of time on the
payload/communication contract.

So given that, the two common ways are 1, adding the version to the URI like
you mentioned, which works fine and is used by some very popular services.

Option 2 is to have the version be either part of the request body or request
header, and if it isn't specified use the latest version.

Each option has pros/cons. Just as 1 example, in Option 1 you can have a front
end service like nginx route to different end points based on the version om
the URI. Thus making load balancing or handling special clients pretty easy.
In Option 2 you could still do this but it would take either inspection of the
header or another layer to inspect the payload, which isn't as efficient.

------
djb_hackernews
no, do not make one big if else block.

I havent used restlet but I think what you want is hierarchical routing:
[http://restlet.com/technical-resources/restlet-
framework/gui...](http://restlet.com/technical-resources/restlet-
framework/guide/2.3/core/routing/hierarchical-uris)

You'd have a Restlet impl for each version of the API

------
gt565k
namespacing and routing mate. Just have another controller that maps to v1 or
v2...

