How to do API Versioning?

[Geetha]

I have a query in my usecase. Please help me to solve.

This is my scenario :

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.

If my API looks like this : http://localhost:8080/example.com/v2/hello Then In my source code how to map the version with appropriate functionality?

For example :

If(version == 1) {//Do Version 1 Source Code} else If(version == 2) {//Do Version 2 Source Code} else If(version == 3) {//Do Version 3 Source Code} ………..

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.

I have read that we can use annotations for handling API versioning. But I don't know what are the annotations available in restlet framework. Please let me know.

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

[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.

[jlouvel]

Restlet team has answered in this GitHub issue: https://github.com/restlet/restlet-framework-java/issues/105...

[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...

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...