OK, thanks for feedback Francesco! So your concern/frustration was primarily about insufficient testing (and thus breaking console) rather than new API design. I completely agree with you.
Best regards. Jan > -----Original Message----- > From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] > Sent: Montag, 28. Januar 2013 10:13 > To: dev@syncope.apache.org > Subject: Re: Discuss: Rest interface for UserRequestService > > On 28/01/2013 09:45, Jan Bernhardt wrote: > > Hi Francesco, > > > >> -----Original Message----- > >> From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] > >> Sent: Freitag, 25. Januar 2013 17:08 > >> To: dev@syncope.apache.org > >> Subject: Re: Discuss: Rest interface for UserRequestService > >> > >> On 25/01/2013 16:56, Christian Schneider wrote: > >>> When doing the CXF version of the UserRequestService I found that > >>> our current UserRequestController does not really follow the rest ideas. > >>> > >>> The problem is that it does follow the idea of doing CRUD operations > >>> on resources. Some methods work with userId others with requestId. > >>> So for example the are create, update and delete operations but they > >>> do not mean the UserRequest but the underlying user. > >>> > >>> So I worked out a new interface that purely works on UserRequest and > >>> only supports POST, READ and DELETE. So basically if you want to > >>> create or delete or update a user you will POST a UserRequestTO in all > cases. > >> cases. > >> > >> Problem: you've already made all these changes *without* discussing > >> this before, > > IMHO I think it is OK to commit new features without discussing method > signature in advanced. Most time it is not possible to think of best design in > advanced, but only while implementing a feature it becomes clear how to > optimize method signatures. Of course if I change something that effects > other code also, this should be discusses previously. Do you expect all > committers to start a discussion before they introduce a new method? > > Of course not, but the whole point was that such change *did* affected > other code: console's Login page, in this case. > > > Since Core REST interface is an important topic for whole project we > already agreed to discuss each REST interface one by one. But since new > REST API will not be used in next syncope release I was expecting that it is > more important to get a first (nice) implementation done and then start > discussion and refactoring afterwards. As mentioned earlier, it is not easy to > make a "perfect" design at first and then start a discussion. > > > > WDYT? > > I agree with this: the problem - now fixed, thanks Christian - was that the > aforementioned refactoring did not consider the side effects on the admin > console, leaving it completely inaccessible. > Maybe you don't realize the impact of this, but it was huge. > > I am completely fine with improving API refactory, but I also think that we > must *all* take care of the side effects of such actions. > > >> once again not taking into any account the domain requirements > > I don't understand this, can you please elaborate? Domain specific > requirements are completely mapped. There is no functionality lost by > making a service RESTful. IMHO I think it is best to preserve all current > functionality while optimizing request behavior to best practices of used > technology. Which domain requirement cannot be covered by using proper > RESTful design? > > I am referring to the match between proper RESTful design (i.e. how to give > access to a service) and the service itself. > We can make a wonderful awarded RESTful interface, but if this doesn't > cover the identity management use cases Syncope is meant to, such > interface is useless. > > Consider the discussion we've had recently about delete: RESTful best > practice says "must return void", we need "must return delete entity". > We ended up with "for anything but users and roles we will adhere > completely to best practice, for users and roles the functional requirement is > more weighted than pure best practice". > This is an example of how I'd think we should match these two aspects. > > >> nor the compatibility with existing components, but only the technology > aspects. > > I also don't understand this. Could you please explain some more? We > previously agreed, that new REST API does not need to be identically with > current REST URLs, only functional compatibility was required. That's why I > started [1] to document how REST API will change from Spring to CXF > migration. So people using their own Console client will have to migrate in > any case. And if this is the case, why not using underlying technology > according to best practices? This way we will avoid refactoring API at a later > state, when we run into issues, that could have been avoided by directly > applying best practices of used technology. > > Since we are using JAX-B and JAX-RS annotation in new interfaces, writing a > custom client will become much easier, since client code can be generated > based on annotations. > > We already agreed on the migration path and [1] contains really nice and > useful information for this purpose. > Problems arise when, with purpose of building the new REST interface, > something breaks the old REST interface - that will stay as official > interface for > upcoming 1.1.0 as well. > > As said above, the broken Login page was the trigger for my e-mail, not the > proposal for changes to the new UserRequestInterface, not the fact that > such proposal already modified all methods of the existing > UserRequestController. > > Regards. > > > [1] > > > https://cwiki.apache.org/confluence/display/SYNCOPE/REST+API+upgrade# > R > > ESTAPIupgrade-RoleService > > -- > Francesco Chicchiriccò > > ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member > http://people.apache.org/~ilgrosso/
