Hi Jan
On 05/11/12 11:55, Jan Bernhardt wrote:
Hi @all,
I'm currently thinking of the be way to handle multi versions within Syncope
REST API. I would like to get your feedback on how this could be done best.
Even thou we will do our best to keep the REST API as stable as possible, so
that 3rd party applications using syncope, don't have to update their code
frequently, there will be changes necessary from time to time. By providing a
mechanism to choose a specific API version, we should be able to support
backwards-compatibility much better.
1. URL encoded Version Number
Since every Call to Syncope core will be done throw an REST call on a specific
URL, we could include a Version-Number in this URL to identify the targeted
(request/response) version.
Sample: http://www.myserver.com/syncope/rest/v2.0/user
2. Version Number included in Namespace
We could also use different Namespaces (that contain a version number) for
Request/Response messages.
I think, that the first approach would be the best choice because not all
contents are XML/Namespace based.
Do you have further ideas or arguments for one or the other solution?
Starting from the 1st approach seems like a good idea.
You can also consider supporting both URIs, ex,
"http://www.myserver.com/syncope/rest/v2.0/user"; and
http://www.myserver.com/syncope/rest/user"; both resolving to the same
service class, with "http://www.myserver.com/syncope/rest/user"; always
resolving to the current service code. You can do it in CXF by
configuring CXFServlet to redirect to the current (versioned) URI, or
have two JAX-RS endpoints listening at different addresses and sharing
the same service bean.
Also, FYI, CXF TransformationFeature will help with keeping both
backward and forward compatibility at the XML level:
http://cxf.apache.org/docs/transformationfeature.html
Andrei S. has just added XSLTFeature too to get more complex cases covered
As a side note, may be it is possible to drop 'rest' from URI.
Cheers, Sergey
Best regards
Jan
