[DISCUSS] REST API URL

[Jan Bernhardt <jb...@talend.com>]

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?

Best regards
Jan

Re: [DISCUSS] REST API URL

[Sergey Beryozkin <sb...@gmail.com>]

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
>