On 28/01/2013 09:45, Jan Bernhardt wrote:
Hi Francesco,
-----Original Message-----
From: Francesco Chicchiriccò [mailto:[email protected]]
Sent: Freitag, 25. Januar 2013 17:08
To: [email protected]
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#RESTAPIupgrade-RoleService
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
