You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@syncope.apache.org by Jan Bernhardt <jb...@talend.com> on 2012/10/30 12:31:15 UTC
REST Interface
Hi @all,
I'm currently working on replacing Spring Webservice Stack with CXF. By doing this I discovered a couple of issues, that I would like to discuss here.
1. Syncope's REST API is only defined throw classes. My suggestion would be to extract Interfaces from these Classes and place these in a new package 'org.apache.syncope.core.rest.api'. All REST and security annotations would be located with the interface.
By doing this we would have a better chance to provide a stable REST interface and allow others to provide their own implementations.
2. Since replacing the WS-Stack will affect many classes, I would like to use this opportunity and also refactor the REST URLs to become more RESTfull-Style. Currently there are URLs like '/create', '/update' and '/delete/{roleId}'. I would like to refactor this to use matching HTTP Operations (e.g. POST, PUT and DELETE), instead of coding the operation name inside the URL.
Of course this will have a major effect on the REST API, but from my point of view, these changes should be done rather sooner than later (before many 3rd party solutions are using Syncope).
Of course we could make sure that this new REST API could still be backwards compatible, but I would rather deliver the new REST API with sufficient documentation within the next major release and not clutter the new interfaces with backwards-compatible code.
What are your thoughts?
Best regards
Jan
Re: REST Interface
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 30/10/2012 13:22, Jan Bernhardt wrote:
> Hi Francesco,
>
> here mid be another opportunity for improvements. ;-)
>
> The module syncope-client is quite confusing at the moment, because it contains mainly model classes that are used by client and server components. My suggestion would be to create another module 'syncope-common' and place all common model and interface classes in there. This would cause the following dependencies:
>
> syncope-common -> (none)
> syncope-core -> syncope-common
> syncope-client -> syncope-common
> syncope-console -> syncope-client -> syncope-common
>
> What are your thoughts?
Agreed; and when you want to make your own REST client for Syncope, you
just need to depend on the (new) syncope-client.
...but this is basically SYNCOPE-150 ;-)
Regards.
>> -----Original Message-----
>> From: Francesco Chicchiriccò [mailto:ilgrosso@apache.org]
>> Sent: Dienstag, 30. Oktober 2012 12:46
>> To: syncope-dev@incubator.apache.org
>> Subject: Re: REST Interface
>>
>> On 30/10/2012 12:31, Jan Bernhardt wrote:
>>> Hi @all,
>>>
>>> I'm currently working on replacing Spring Webservice Stack with CXF. By
>> doing this I discovered a couple of issues, that I would like to discuss here.
>>>
>>> 1. Syncope's REST API is only defined throw classes. My suggestion
>> would be to extract Interfaces from these Classes and place these in a new
>> package 'org.apache.syncope.core.rest.api'. All REST and security annotations
>> would be located with the interface.
>>> By doing this we would have a better chance to provide a stable REST
>> interface and allow others to provide their own implementations.
>>
>> +1
>> I would also:
>> 1. move this new package 'org.apache.syncope.core.rest.api' to syncope-
>> client module 2. refactor all syncope-console classes '*RestClient' to
>> implement the new APIs and move such refactored classes to syncope-client
>> module as well
>>
>>> 2. Since replacing the WS-Stack will affect many classes, I would like to
>> use this opportunity and also refactor the REST URLs to become more
>> RESTfull-Style. Currently there are URLs like '/create', '/update' and
>> '/delete/{roleId}'. I would like to refactor this to use matching HTTP
>> Operations (e.g. POST, PUT and DELETE), instead of coding the operation
>> name inside the URL.
>>
>> A big +1 for this.
>>
>>> Of course this will have a major effect on the REST API, but from my point
>> of view, these changes should be done rather sooner than later (before
>> many 3rd party solutions are using Syncope).
>>> Of course we could make sure that this new REST API could still be
>> backwards compatible, but I would rather deliver the new REST API with
>> sufficient documentation within the next major release and not clutter the
>> new interfaces with backwards-compatible code.
>>
>> I wouldn't care about backward compatibility: we are making this change for
>> a new major version, and the new client classes (mentioned above) should
>> make things really smooth.
>>
>> Regards.
--
Francesco Chicchiriccò
ASF Member, Apache Cocoon PMC and Apache Syncope PPMC Member
http://people.apache.org/~ilgrosso/
RE: REST Interface
Posted by Jan Bernhardt <jb...@talend.com>.
Hi Francesco,
here mid be another opportunity for improvements. ;-)
The module syncope-client is quite confusing at the moment, because it contains mainly model classes that are used by client and server components. My suggestion would be to create another module 'syncope-common' and place all common model and interface classes in there. This would cause the following dependencies:
syncope-common -> (none)
syncope-core -> syncope-common
syncope-client -> syncope-common
syncope-console -> syncope-client -> syncope-common
What are your thoughts?
Best regards
Jan
> -----Original Message-----
> From: Francesco Chicchiriccò [mailto:ilgrosso@apache.org]
> Sent: Dienstag, 30. Oktober 2012 12:46
> To: syncope-dev@incubator.apache.org
> Subject: Re: REST Interface
>
> On 30/10/2012 12:31, Jan Bernhardt wrote:
> > Hi @all,
> >
> > I'm currently working on replacing Spring Webservice Stack with CXF. By
> doing this I discovered a couple of issues, that I would like to discuss here.
> >
> >
> > 1. Syncope's REST API is only defined throw classes. My suggestion
> would be to extract Interfaces from these Classes and place these in a new
> package 'org.apache.syncope.core.rest.api'. All REST and security annotations
> would be located with the interface.
> > By doing this we would have a better chance to provide a stable REST
> interface and allow others to provide their own implementations.
>
> +1
> I would also:
> 1. move this new package 'org.apache.syncope.core.rest.api' to syncope-
> client module 2. refactor all syncope-console classes '*RestClient' to
> implement the new APIs and move such refactored classes to syncope-client
> module as well
>
> > 2. Since replacing the WS-Stack will affect many classes, I would like to
> use this opportunity and also refactor the REST URLs to become more
> RESTfull-Style. Currently there are URLs like '/create', '/update' and
> '/delete/{roleId}'. I would like to refactor this to use matching HTTP
> Operations (e.g. POST, PUT and DELETE), instead of coding the operation
> name inside the URL.
>
> A big +1 for this.
>
> > Of course this will have a major effect on the REST API, but from my point
> of view, these changes should be done rather sooner than later (before
> many 3rd party solutions are using Syncope).
> > Of course we could make sure that this new REST API could still be
> backwards compatible, but I would rather deliver the new REST API with
> sufficient documentation within the next major release and not clutter the
> new interfaces with backwards-compatible code.
>
> I wouldn't care about backward compatibility: we are making this change for
> a new major version, and the new client classes (mentioned above) should
> make things really smooth.
>
> Regards.
>
> --
> Francesco Chicchiriccò
>
> ASF Member, Apache Cocoon PMC and Apache Syncope PPMC Member
> http://people.apache.org/~ilgrosso/
Re: REST Interface
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 30/10/2012 12:31, Jan Bernhardt wrote:
> Hi @all,
>
> I'm currently working on replacing Spring Webservice Stack with CXF. By doing this I discovered a couple of issues, that I would like to discuss here.
>
>
> 1. Syncope's REST API is only defined throw classes. My suggestion would be to extract Interfaces from these Classes and place these in a new package 'org.apache.syncope.core.rest.api'. All REST and security annotations would be located with the interface.
> By doing this we would have a better chance to provide a stable REST interface and allow others to provide their own implementations.
+1
I would also:
1. move this new package 'org.apache.syncope.core.rest.api' to
syncope-client module
2. refactor all syncope-console classes '*RestClient' to implement the
new APIs and move such refactored classes to syncope-client module as well
> 2. Since replacing the WS-Stack will affect many classes, I would like to use this opportunity and also refactor the REST URLs to become more RESTfull-Style. Currently there are URLs like '/create', '/update' and '/delete/{roleId}'. I would like to refactor this to use matching HTTP Operations (e.g. POST, PUT and DELETE), instead of coding the operation name inside the URL.
A big +1 for this.
> Of course this will have a major effect on the REST API, but from my point of view, these changes should be done rather sooner than later (before many 3rd party solutions are using Syncope).
> Of course we could make sure that this new REST API could still be backwards compatible, but I would rather deliver the new REST API with sufficient documentation within the next major release and not clutter the new interfaces with backwards-compatible code.
I wouldn't care about backward compatibility: we are making this change
for a new major version, and the new client classes (mentioned above)
should make things really smooth.
Regards.
--
Francesco Chicchiriccò
ASF Member, Apache Cocoon PMC and Apache Syncope PPMC Member
http://people.apache.org/~ilgrosso/
Re: REST Interface
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 30/10/2012 12:55, Jan Bernhardt wrote:
> Good idea.
>
> I'll create a new wiki page for this topic. Is it possible to create wiki pages that are not public until the new REST API would be released?
The page is created at [1], with read and write restrictions for
syncope-committers.
Regards.
[1] https://cwiki.apache.org/confluence/display/SYNCOPE/REST+API+upgrade
>> -----Original Message-----
>> From: ernst Developer [mailto:ernst.developer@gmail.com]
>> Sent: Dienstag, 30. Oktober 2012 12:52
>> To: syncope-dev@incubator.apache.org
>> Subject: Re: REST Interface
>>
>> Hi,
>>
>> This is a great improvement: +1
>>
>> On remark though. I would like to suggest to make a list on the wiki of the
>> mapping of the current REST API to the new REST API. This will be very useful
>> when migrating from a previous version.
>>
>> Regards,
>> Ernst
>>
>> 2012/10/30 Jan Bernhardt <jb...@talend.com>
>>
>>> Hi @all,
>>>
>>> I'm currently working on replacing Spring Webservice Stack with CXF.
>>> By doing this I discovered a couple of issues, that I would like to
>>> discuss here.
>>>
>>>
>>> 1. Syncope's REST API is only defined throw classes. My suggestion
>>> would be to extract Interfaces from these Classes and place these in a
>>> new package 'org.apache.syncope.core.rest.api'. All REST and security
>>> annotations would be located with the interface.
>>> By doing this we would have a better chance to provide a stable REST
>>> interface and allow others to provide their own implementations.
>>>
>>> 2. Since replacing the WS-Stack will affect many classes, I would
>>> like to use this opportunity and also refactor the REST URLs to become
>>> more RESTfull-Style. Currently there are URLs like '/create',
>>> '/update' and '/delete/{roleId}'. I would like to refactor this to use
>>> matching HTTP Operations (e.g. POST, PUT and DELETE), instead of
>>> coding the operation name inside the URL.
>>> Of course this will have a major effect on the REST API, but from my
>>> point of view, these changes should be done rather sooner than later
>>> (before many 3rd party solutions are using Syncope).
>>> Of course we could make sure that this new REST API could still be
>>> backwards compatible, but I would rather deliver the new REST API with
>>> sufficient documentation within the next major release and not clutter
>>> the new interfaces with backwards-compatible code.
>>>
>>> What are your thoughts?
>>>
>>> Best regards
>>> Jan
--
Francesco Chicchiriccò
ASF Member, Apache Cocoon PMC and Apache Syncope PPMC Member
http://people.apache.org/~ilgrosso/
RE: REST Interface
Posted by Jan Bernhardt <jb...@talend.com>.
Good idea.
I'll create a new wiki page for this topic. Is it possible to create wiki pages that are not public until the new REST API would be released?
Regards
Jan
> -----Original Message-----
> From: ernst Developer [mailto:ernst.developer@gmail.com]
> Sent: Dienstag, 30. Oktober 2012 12:52
> To: syncope-dev@incubator.apache.org
> Subject: Re: REST Interface
>
> Hi,
>
> This is a great improvement: +1
>
> On remark though. I would like to suggest to make a list on the wiki of the
> mapping of the current REST API to the new REST API. This will be very useful
> when migrating from a previous version.
>
> Regards,
> Ernst
>
> 2012/10/30 Jan Bernhardt <jb...@talend.com>
>
> > Hi @all,
> >
> > I'm currently working on replacing Spring Webservice Stack with CXF.
> > By doing this I discovered a couple of issues, that I would like to
> > discuss here.
> >
> >
> > 1. Syncope's REST API is only defined throw classes. My suggestion
> > would be to extract Interfaces from these Classes and place these in a
> > new package 'org.apache.syncope.core.rest.api'. All REST and security
> > annotations would be located with the interface.
> > By doing this we would have a better chance to provide a stable REST
> > interface and allow others to provide their own implementations.
> >
> > 2. Since replacing the WS-Stack will affect many classes, I would
> > like to use this opportunity and also refactor the REST URLs to become
> > more RESTfull-Style. Currently there are URLs like '/create',
> > '/update' and '/delete/{roleId}'. I would like to refactor this to use
> > matching HTTP Operations (e.g. POST, PUT and DELETE), instead of
> > coding the operation name inside the URL.
> > Of course this will have a major effect on the REST API, but from my
> > point of view, these changes should be done rather sooner than later
> > (before many 3rd party solutions are using Syncope).
> > Of course we could make sure that this new REST API could still be
> > backwards compatible, but I would rather deliver the new REST API with
> > sufficient documentation within the next major release and not clutter
> > the new interfaces with backwards-compatible code.
> >
> > What are your thoughts?
> >
> > Best regards
> > Jan
> >
> >
Re: REST Interface
Posted by ernst Developer <er...@gmail.com>.
Hi,
This is a great improvement: +1
On remark though. I would like to suggest to make a list on the wiki of the
mapping of the current REST API to the new REST API. This will be very
useful when migrating from a previous version.
Regards,
Ernst
2012/10/30 Jan Bernhardt <jb...@talend.com>
> Hi @all,
>
> I'm currently working on replacing Spring Webservice Stack with CXF. By
> doing this I discovered a couple of issues, that I would like to discuss
> here.
>
>
> 1. Syncope's REST API is only defined throw classes. My suggestion
> would be to extract Interfaces from these Classes and place these in a new
> package 'org.apache.syncope.core.rest.api'. All REST and security
> annotations would be located with the interface.
> By doing this we would have a better chance to provide a stable REST
> interface and allow others to provide their own implementations.
>
> 2. Since replacing the WS-Stack will affect many classes, I would
> like to use this opportunity and also refactor the REST URLs to become more
> RESTfull-Style. Currently there are URLs like '/create', '/update' and
> '/delete/{roleId}'. I would like to refactor this to use matching HTTP
> Operations (e.g. POST, PUT and DELETE), instead of coding the operation
> name inside the URL.
> Of course this will have a major effect on the REST API, but from my point
> of view, these changes should be done rather sooner than later (before many
> 3rd party solutions are using Syncope).
> Of course we could make sure that this new REST API could still be
> backwards compatible, but I would rather deliver the new REST API with
> sufficient documentation within the next major release and not clutter the
> new interfaces with backwards-compatible code.
>
> What are your thoughts?
>
> Best regards
> Jan
>
>
Re: REST Interface
Posted by Fabio Martelli <fa...@gmail.com>.
Il giorno 30/ott/2012, alle ore 12.31, Jan Bernhardt ha scritto:
> Hi @all,
>
> I'm currently working on replacing Spring Webservice Stack with CXF. By doing this I discovered a couple of issues, that I would like to discuss here.
>
>
> 1. Syncope's REST API is only defined throw classes. My suggestion would be to extract Interfaces from these Classes and place these in a new package 'org.apache.syncope.core.rest.api'. All REST and security annotations would be located with the interface.
> By doing this we would have a better chance to provide a stable REST interface and allow others to provide their own implementations.
>
> 2. Since replacing the WS-Stack will affect many classes, I would like to use this opportunity and also refactor the REST URLs to become more RESTfull-Style. Currently there are URLs like '/create', '/update' and '/delete/{roleId}'. I would like to refactor this to use matching HTTP Operations (e.g. POST, PUT and DELETE), instead of coding the operation name inside the URL.
> Of course this will have a major effect on the REST API, but from my point of view, these changes should be done rather sooner than later (before many 3rd party solutions are using Syncope).
> Of course we could make sure that this new REST API could still be backwards compatible, but I would rather deliver the new REST API with sufficient documentation within the next major release and not clutter the new interfaces with backwards-compatible code.
>
> What are your thoughts?
Fine for me but, please take care of the admin console as well.
Regards,
F.