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 2013/01/23 09:06:02 UTC
[DISCUSS] New REST Service Interfaces - ConfigurationService
Hi Syncoper,
here are the proposed changes for our Configuration Service:
* Changing Create response type to javax.ws.rs.core.Response. This way we can set response HTTP Status code (201 created) without requiring HttpServletResponse as method parameter. Also according to best RESTful practices instead of returning newly created object directly, only URL for new Object (Configuration) will be returned. Console does not even care about created response, thus network traffic can be reduced, by not sending object (configuration). If consumer does care about new object he can easily follow provided URL (in response) and retrieve new object.
* Changed ModelAndView response type to Set<ValidatorTO> / Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO and MailTemplateTO.
* Changed return type from update() and delete() to void, since console does not even care about it, and I think this should be best practice anyway, since consumer knows updates object already and does not care about deleted ones, therefore there is no need to send them over the network.
Any objections?
Best regards.
Jan
> -----Original Message-----
> From: Jan Bernhardt [mailto:jbernhardt@talend.com]
> Sent: Donnerstag, 17. Januar 2013 14:04
> To: dev@syncope.apache.org
> Subject: RE: [Discussion] New REST Service Interfaces - Entitlements
>
> Hi Syncoper,
>
> The following changes are proposed regarding AuthenticationController:
>
> === Renaming Service ===
> Rename AuthenticationController to EntitlementService(Impl), since
> containing methods have little to nothing to do with authentication. It is only
> about Entitlements...
>
> === Changing response Type ===
> listEntitlements() returns a List<String> whereas getEntitlements() returns a
> Set<String>.
>
> From my point of view both methods should return a SET since entitlements
> have no order and cannot exists or be assigned more than once.
>
> Due to some JAX-B / JAX-RS limitations, it is not possible to return a collection
> with primitive data types in java. A wrapper class is required, e.g.
> Set<EntitlementTO>.
>
> EntitlementTO can be modeled in one of two ways:
>
> Option 1:
> <EntitlementTOs>
> <EntitlementTO>ROLE_ADMIN</EntitlementTO>
> <EntitlementTO>ROLE_SUPERUSER</EntitlementTO>
> </EntitlementTOs>
>
> Option 2:
> <EntitlementTOs>
> <EntitlementTO>
> <name>ROLE_ADMIN</name>
> </EntitlementTO>
> <EntitlementTO>
> <name> ROLE_SUPERUSER </name>
> </EntitlementTO>
> </EntitlementTOs>
>
> Option 1 matches more or less current marshaling. I personally would prefer
> Option 2 because this would give us the opportunity to easily extend
> EntitlementTO at a later point (if needed) without becoming incompatible
> with previous version.
>
> WDYT?
>
> All of these changes will not apply to current Spring Controller/Services, but
> only future CXF REST Service. So AuthenticationController will not be
> renamed now, and responsetype of AuthenticationController will not
> change. Changes only apply for new Service Interface and (Proxy)
> Implementation.
>
> Best regards.
> Jan
Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Fabio Martelli <fa...@gmail.com>.
Il giorno 23/gen/2013, alle ore 10.39, Jan Bernhardt ha scritto:
>> -----Original Message-----
>> From: Fabio Martelli [mailto:fabio.martelli@gmail.com]
>> Sent: Mittwoch, 23. Januar 2013 10:29
>> To: dev@syncope.apache.org
>> Subject: Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
>>
>>
>> Il giorno 23/gen/2013, alle ore 09.54, Francesco Chicchiriccò ha scritto:
>>
>>> On 23/01/2013 09:06, Jan Bernhardt wrote:
>>>> Hi Syncoper,
>>>>
>>>> here are the proposed changes for our Configuration Service:
>>>>
>>>> * Changing Create response type to javax.ws.rs.core.Response. This way
>> we can set response HTTP Status code (201 created) without requiring
>> HttpServletResponse as method parameter. Also according to best RESTful
>> practices instead of returning newly created object directly, only URL for new
>> Object (Configuration) will be returned. Console does not even care about
>> created response, thus network traffic can be reduced, by not sending
>> object (configuration). If consumer does care about new object he can easily
>> follow provided URL (in response) and retrieve new object.
>>>
>>> If this is a REST best practice, fine for me.
>>>
>>>> * Changed ModelAndView response type to Set<ValidatorTO> /
>> Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO
>> and MailTemplateTO.
>>>
>>> Fine.
>>>
>>>> * Changed return type from update() and delete() to void, since console
>> does not even care about it, and I think this should be best practice anyway,
>> since consumer knows updates object already and does not care about
>> deleted ones, therefore there is no need to send them over the network.
>>>
>>> About update() I can agree with you: since the updated entity (user, role,
>> ...) is still there, an URL can be returned as in the create() case reported
>> above.
>
> Technically it would be no problem to return such a URL, but I don't see much value in doing this. Update operations are performed with a PUT Operation. You can use the same URL with a GET Operation to retrieve updated object. This behavior has changed to URL pattern of Spring REST services, where there was a */read/* and */update/* path. With CXF Services I focused on using matching HTTP operations as this also applies to RESTful best practices.
>
>>>
>>> About delete() however, not retuning the deleted entity can break the
>> current feature: once again, please don't think that the admin console is the
>> only REST client out there.
>
> Old (Spring) REST API will not be changed. New CXF URLs in most cases will not match old URLs (see read, update, delete behavior mentioned above), so clients would have to be updated anyway. And I don't see a problem for a client to first make a GET call an a resource and then following a DELETE call, if he is interested in deleted resource. (which I expect not to be the case most often).
>
>>
>> +1
>> The response provided by the delete is also used to know the outcome of
>> the deletion performed onto the external resources.
>
> I agree with you for Roles and Users since changes will be propagated to other systems. But all other resources in Syncope are only internal in Core. Therefore I would suggest to not return anything for delete operation except for users and roles.
ok for me
>
> Best regards.
> Jan
>
>>
>>> Regards.
>>>
>>> --
>>> Francesco Chicchiriccò
>>>
>>> ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
>>> http://people.apache.org/~ilgrosso/
>>>
>
RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Jan Bernhardt <jb...@talend.com>.
> -----Original Message-----
> From: Fabio Martelli [mailto:fabio.martelli@gmail.com]
> Sent: Mittwoch, 23. Januar 2013 10:29
> To: dev@syncope.apache.org
> Subject: Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
>
>
> Il giorno 23/gen/2013, alle ore 09.54, Francesco Chicchiriccò ha scritto:
>
> > On 23/01/2013 09:06, Jan Bernhardt wrote:
> >> Hi Syncoper,
> >>
> >> here are the proposed changes for our Configuration Service:
> >>
> >> * Changing Create response type to javax.ws.rs.core.Response. This way
> we can set response HTTP Status code (201 created) without requiring
> HttpServletResponse as method parameter. Also according to best RESTful
> practices instead of returning newly created object directly, only URL for new
> Object (Configuration) will be returned. Console does not even care about
> created response, thus network traffic can be reduced, by not sending
> object (configuration). If consumer does care about new object he can easily
> follow provided URL (in response) and retrieve new object.
> >
> > If this is a REST best practice, fine for me.
> >
> >> * Changed ModelAndView response type to Set<ValidatorTO> /
> Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO
> and MailTemplateTO.
> >
> > Fine.
> >
> >> * Changed return type from update() and delete() to void, since console
> does not even care about it, and I think this should be best practice anyway,
> since consumer knows updates object already and does not care about
> deleted ones, therefore there is no need to send them over the network.
> >
> > About update() I can agree with you: since the updated entity (user, role,
> ...) is still there, an URL can be returned as in the create() case reported
> above.
Technically it would be no problem to return such a URL, but I don't see much value in doing this. Update operations are performed with a PUT Operation. You can use the same URL with a GET Operation to retrieve updated object. This behavior has changed to URL pattern of Spring REST services, where there was a */read/* and */update/* path. With CXF Services I focused on using matching HTTP operations as this also applies to RESTful best practices.
> >
> > About delete() however, not retuning the deleted entity can break the
> current feature: once again, please don't think that the admin console is the
> only REST client out there.
Old (Spring) REST API will not be changed. New CXF URLs in most cases will not match old URLs (see read, update, delete behavior mentioned above), so clients would have to be updated anyway. And I don't see a problem for a client to first make a GET call an a resource and then following a DELETE call, if he is interested in deleted resource. (which I expect not to be the case most often).
>
> +1
> The response provided by the delete is also used to know the outcome of
> the deletion performed onto the external resources.
I agree with you for Roles and Users since changes will be propagated to other systems. But all other resources in Syncope are only internal in Core. Therefore I would suggest to not return anything for delete operation except for users and roles.
Best regards.
Jan
>
> > Regards.
> >
> > --
> > Francesco Chicchiriccò
> >
> > ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
> > http://people.apache.org/~ilgrosso/
> >
Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Fabio Martelli <fa...@gmail.com>.
Il giorno 23/gen/2013, alle ore 09.54, Francesco Chicchiriccò ha scritto:
> On 23/01/2013 09:06, Jan Bernhardt wrote:
>> Hi Syncoper,
>>
>> here are the proposed changes for our Configuration Service:
>>
>> * Changing Create response type to javax.ws.rs.core.Response. This way we can set response HTTP Status code (201 created) without requiring HttpServletResponse as method parameter. Also according to best RESTful practices instead of returning newly created object directly, only URL for new Object (Configuration) will be returned. Console does not even care about created response, thus network traffic can be reduced, by not sending object (configuration). If consumer does care about new object he can easily follow provided URL (in response) and retrieve new object.
>
> If this is a REST best practice, fine for me.
>
>> * Changed ModelAndView response type to Set<ValidatorTO> / Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO and MailTemplateTO.
>
> Fine.
>
>> * Changed return type from update() and delete() to void, since console does not even care about it, and I think this should be best practice anyway, since consumer knows updates object already and does not care about deleted ones, therefore there is no need to send them over the network.
>
> About update() I can agree with you: since the updated entity (user, role, ...) is still there, an URL can be returned as in the create() case reported above.
>
> About delete() however, not retuning the deleted entity can break the current feature: once again, please don't think that the admin console is the only REST client out there.
+1
The response provided by the delete is also used to know the outcome of the deletion performed onto the external resources.
> Regards.
>
> --
> Francesco Chicchiriccò
>
> ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
> http://people.apache.org/~ilgrosso/
>
Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 23/01/2013 09:06, Jan Bernhardt wrote:
> Hi Syncoper,
>
> here are the proposed changes for our Configuration Service:
>
> * Changing Create response type to javax.ws.rs.core.Response. This way we can set response HTTP Status code (201 created) without requiring HttpServletResponse as method parameter. Also according to best RESTful practices instead of returning newly created object directly, only URL for new Object (Configuration) will be returned. Console does not even care about created response, thus network traffic can be reduced, by not sending object (configuration). If consumer does care about new object he can easily follow provided URL (in response) and retrieve new object.
If this is a REST best practice, fine for me.
> * Changed ModelAndView response type to Set<ValidatorTO> / Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO and MailTemplateTO.
Fine.
> * Changed return type from update() and delete() to void, since console does not even care about it, and I think this should be best practice anyway, since consumer knows updates object already and does not care about deleted ones, therefore there is no need to send them over the network.
About update() I can agree with you: since the updated entity (user,
role, ...) is still there, an URL can be returned as in the create()
case reported above.
About delete() however, not retuning the deleted entity can break the
current feature: once again, please don't think that the admin console
is the only REST client out there.
Regards.
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Sergey Beryozkin <sb...@gmail.com>.
On 23/01/13 10:16, Jan Bernhardt wrote:
>> -----Original Message-----
>> From: Sergey Beryozkin [mailto:sberyozkin@gmail.com]
>> Sent: Mittwoch, 23. Januar 2013 10:52
>> To: dev@syncope.apache.org
>> Subject: Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
>>
>> Hi Jan
>> On 23/01/13 08:06, Jan Bernhardt wrote:
>>> Hi Syncoper,
>>>
>>> here are the proposed changes for our Configuration Service:
>>>
>>> * Changing Create response type to javax.ws.rs.core.Response. This way
>> we can set response HTTP Status code (201 created) without requiring
>> HttpServletResponse as method parameter. Also according to best RESTful
>> practices instead of returning newly created object directly, only URL for new
>> Object (Configuration) will be returned. Console does not even care about
>> created response, thus network traffic can be reduced, by not sending
>> object (configuration). If consumer does care about new object he can easily
>> follow provided URL (in response) and retrieve new object.
>>>
>> I think it is fine echoing back the created resource representation (alongside
>> Location) when it can help the client to avoid the extra round trip, I guess it
>> depends on the actual requirements of the console client
>
> I would think that for roles and users it would be best to directly responding created objects since they contain propagation information.
> For all other resources our console does not even care about, so there is no need to directly respond them.
> If other "consoles" do care, they can follow the provided URL or call interface read operation with provided ID (from response header).
>
>>
>>> * Changed ModelAndView response type to Set<ValidatorTO> /
>> Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO
>> and MailTemplateTO.
>>>
>> One thing I should mention is that auto-describing the explicit collections is
>> tricky in WADL, though of course one can register a custom WADL document
>> with CXF; personally I prefer using collection wrapper beans - it is simpler to
>> get them described and also easier to attach some more metadata to such
>> collection in the form of the wrapper properties, that said, returning the
>> explicit collections will also work
>
> Interesting point. Thanks for this feedback Sergey. I currently do not see any need for additional metadata, so I would rather want to avoid additional refactoring work, even thou I think using a "WrapperClass" would be a better interface design.
> Do you expect this WADL generation problem to remain for a long time? I would rather not want to change my interface design due to a temporal missing feature of another component...
I did not say there was a definite problem :-) but it can be tricky;
when we have an explicit collection we kind of lose control over how the
wrapper element may look like - the runtime tries its best to deduce the
most suitable wrapper name - and this name can also be configured to
make it predictable.
The more complex problem is to do with the fact that the actual schema
(wadl:grammar) does not have a schema element describing such a
syntesized wrapper generated by JAXB - so the generator tries to modify
the generated schema block manually - we have a test for List of JAXB
beans - I guess that should work for Sets too - most likely yes - would
be a trivial fix if not - but this custom schema modification has not
been extensively tested so there could be some issues there, nnot 100% sure
But as I said, a custom WADL document can also be registered if the
default auto-generated one won't offer the perfect description
Cheers, Sergey
>
> Best regards.
> Jan
>
>>
>> Cheers, Sergey
>>
>>> * Changed return type from update() and delete() to void, since console
>> does not even care about it, and I think this should be best practice anyway,
>> since consumer knows updates object already and does not care about
>> deleted ones, therefore there is no need to send them over the network.
>>>
>>> Any objections?
>>>
>>> Best regards.
>>> Jan
>>>
>>>
>>>> -----Original Message-----
>>>> From: Jan Bernhardt [mailto:jbernhardt@talend.com]
>>>> Sent: Donnerstag, 17. Januar 2013 14:04
>>>> To: dev@syncope.apache.org
>>>> Subject: RE: [Discussion] New REST Service Interfaces - Entitlements
>>>>
>>>> Hi Syncoper,
>>>>
>>>> The following changes are proposed regarding AuthenticationController:
>>>>
>>>> === Renaming Service ===
>>>> Rename AuthenticationController to EntitlementService(Impl), since
>>>> containing methods have little to nothing to do with authentication.
>>>> It is only about Entitlements...
>>>>
>>>> === Changing response Type ===
>>>> listEntitlements() returns a List<String> whereas getEntitlements()
>>>> returns a Set<String>.
>>>>
>>>> From my point of view both methods should return a SET since
>>>> entitlements have no order and cannot exists or be assigned more than
>> once.
>>>>
>>>> Due to some JAX-B / JAX-RS limitations, it is not possible to return
>>>> a collection with primitive data types in java. A wrapper class is required,
>> e.g.
>>>> Set<EntitlementTO>.
>>>>
>>>> EntitlementTO can be modeled in one of two ways:
>>>>
>>>> Option 1:
>>>> <EntitlementTOs>
>>>> <EntitlementTO>ROLE_ADMIN</EntitlementTO>
>>>> <EntitlementTO>ROLE_SUPERUSER</EntitlementTO>
>>>> </EntitlementTOs>
>>>>
>>>> Option 2:
>>>> <EntitlementTOs>
>>>> <EntitlementTO>
>>>> <name>ROLE_ADMIN</name>
>>>> </EntitlementTO>
>>>> <EntitlementTO>
>>>> <name> ROLE_SUPERUSER</name>
>>>> </EntitlementTO>
>>>> </EntitlementTOs>
>>>>
>>>> Option 1 matches more or less current marshaling. I personally would
>>>> prefer Option 2 because this would give us the opportunity to easily
>>>> extend EntitlementTO at a later point (if needed) without becoming
>>>> incompatible with previous version.
>>>>
>>>> WDYT?
>>>>
>>>> All of these changes will not apply to current Spring
>>>> Controller/Services, but only future CXF REST Service. So
>>>> AuthenticationController will not be renamed now, and responsetype of
>>>> AuthenticationController will not change. Changes only apply for new
>>>> Service Interface and (Proxy) Implementation.
>>>>
>>>> Best regards.
>>>> Jan
>>
>
RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Jan Bernhardt <jb...@talend.com>.
> -----Original Message-----
> From: Sergey Beryozkin [mailto:sberyozkin@gmail.com]
> Sent: Mittwoch, 23. Januar 2013 10:52
> To: dev@syncope.apache.org
> Subject: Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
>
> Hi Jan
> On 23/01/13 08:06, Jan Bernhardt wrote:
> > Hi Syncoper,
> >
> > here are the proposed changes for our Configuration Service:
> >
> > * Changing Create response type to javax.ws.rs.core.Response. This way
> we can set response HTTP Status code (201 created) without requiring
> HttpServletResponse as method parameter. Also according to best RESTful
> practices instead of returning newly created object directly, only URL for new
> Object (Configuration) will be returned. Console does not even care about
> created response, thus network traffic can be reduced, by not sending
> object (configuration). If consumer does care about new object he can easily
> follow provided URL (in response) and retrieve new object.
> >
> I think it is fine echoing back the created resource representation (alongside
> Location) when it can help the client to avoid the extra round trip, I guess it
> depends on the actual requirements of the console client
I would think that for roles and users it would be best to directly responding created objects since they contain propagation information.
For all other resources our console does not even care about, so there is no need to directly respond them.
If other "consoles" do care, they can follow the provided URL or call interface read operation with provided ID (from response header).
>
> > * Changed ModelAndView response type to Set<ValidatorTO> /
> Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO
> and MailTemplateTO.
> >
> One thing I should mention is that auto-describing the explicit collections is
> tricky in WADL, though of course one can register a custom WADL document
> with CXF; personally I prefer using collection wrapper beans - it is simpler to
> get them described and also easier to attach some more metadata to such
> collection in the form of the wrapper properties, that said, returning the
> explicit collections will also work
Interesting point. Thanks for this feedback Sergey. I currently do not see any need for additional metadata, so I would rather want to avoid additional refactoring work, even thou I think using a "WrapperClass" would be a better interface design.
Do you expect this WADL generation problem to remain for a long time? I would rather not want to change my interface design due to a temporal missing feature of another component...
Best regards.
Jan
>
> Cheers, Sergey
>
> > * Changed return type from update() and delete() to void, since console
> does not even care about it, and I think this should be best practice anyway,
> since consumer knows updates object already and does not care about
> deleted ones, therefore there is no need to send them over the network.
> >
> > Any objections?
> >
> > Best regards.
> > Jan
> >
> >
> >> -----Original Message-----
> >> From: Jan Bernhardt [mailto:jbernhardt@talend.com]
> >> Sent: Donnerstag, 17. Januar 2013 14:04
> >> To: dev@syncope.apache.org
> >> Subject: RE: [Discussion] New REST Service Interfaces - Entitlements
> >>
> >> Hi Syncoper,
> >>
> >> The following changes are proposed regarding AuthenticationController:
> >>
> >> === Renaming Service ===
> >> Rename AuthenticationController to EntitlementService(Impl), since
> >> containing methods have little to nothing to do with authentication.
> >> It is only about Entitlements...
> >>
> >> === Changing response Type ===
> >> listEntitlements() returns a List<String> whereas getEntitlements()
> >> returns a Set<String>.
> >>
> >> From my point of view both methods should return a SET since
> >> entitlements have no order and cannot exists or be assigned more than
> once.
> >>
> >> Due to some JAX-B / JAX-RS limitations, it is not possible to return
> >> a collection with primitive data types in java. A wrapper class is required,
> e.g.
> >> Set<EntitlementTO>.
> >>
> >> EntitlementTO can be modeled in one of two ways:
> >>
> >> Option 1:
> >> <EntitlementTOs>
> >> <EntitlementTO>ROLE_ADMIN</EntitlementTO>
> >> <EntitlementTO>ROLE_SUPERUSER</EntitlementTO>
> >> </EntitlementTOs>
> >>
> >> Option 2:
> >> <EntitlementTOs>
> >> <EntitlementTO>
> >> <name>ROLE_ADMIN</name>
> >> </EntitlementTO>
> >> <EntitlementTO>
> >> <name> ROLE_SUPERUSER</name>
> >> </EntitlementTO>
> >> </EntitlementTOs>
> >>
> >> Option 1 matches more or less current marshaling. I personally would
> >> prefer Option 2 because this would give us the opportunity to easily
> >> extend EntitlementTO at a later point (if needed) without becoming
> >> incompatible with previous version.
> >>
> >> WDYT?
> >>
> >> All of these changes will not apply to current Spring
> >> Controller/Services, but only future CXF REST Service. So
> >> AuthenticationController will not be renamed now, and responsetype of
> >> AuthenticationController will not change. Changes only apply for new
> >> Service Interface and (Proxy) Implementation.
> >>
> >> Best regards.
> >> Jan
>
Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi Jan
On 23/01/13 08:06, Jan Bernhardt wrote:
> Hi Syncoper,
>
> here are the proposed changes for our Configuration Service:
>
> * Changing Create response type to javax.ws.rs.core.Response. This way we can set response HTTP Status code (201 created) without requiring HttpServletResponse as method parameter. Also according to best RESTful practices instead of returning newly created object directly, only URL for new Object (Configuration) will be returned. Console does not even care about created response, thus network traffic can be reduced, by not sending object (configuration). If consumer does care about new object he can easily follow provided URL (in response) and retrieve new object.
>
I think it is fine echoing back the created resource representation
(alongside Location) when it can help the client to avoid the extra
round trip, I guess it depends on the actual requirements of the console
client
> * Changed ModelAndView response type to Set<ValidatorTO> / Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO and MailTemplateTO.
>
One thing I should mention is that auto-describing the explicit
collections is tricky in WADL, though of course one can register a
custom WADL document with CXF; personally I prefer using collection
wrapper beans - it is simpler to get them described and also easier to
attach some more metadata to such collection in the form of the wrapper
properties, that said, returning the explicit collections will also work
Cheers, Sergey
> * Changed return type from update() and delete() to void, since console does not even care about it, and I think this should be best practice anyway, since consumer knows updates object already and does not care about deleted ones, therefore there is no need to send them over the network.
>
> Any objections?
>
> Best regards.
> Jan
>
>
>> -----Original Message-----
>> From: Jan Bernhardt [mailto:jbernhardt@talend.com]
>> Sent: Donnerstag, 17. Januar 2013 14:04
>> To: dev@syncope.apache.org
>> Subject: RE: [Discussion] New REST Service Interfaces - Entitlements
>>
>> Hi Syncoper,
>>
>> The following changes are proposed regarding AuthenticationController:
>>
>> === Renaming Service ===
>> Rename AuthenticationController to EntitlementService(Impl), since
>> containing methods have little to nothing to do with authentication. It is only
>> about Entitlements...
>>
>> === Changing response Type ===
>> listEntitlements() returns a List<String> whereas getEntitlements() returns a
>> Set<String>.
>>
>> From my point of view both methods should return a SET since entitlements
>> have no order and cannot exists or be assigned more than once.
>>
>> Due to some JAX-B / JAX-RS limitations, it is not possible to return a collection
>> with primitive data types in java. A wrapper class is required, e.g.
>> Set<EntitlementTO>.
>>
>> EntitlementTO can be modeled in one of two ways:
>>
>> Option 1:
>> <EntitlementTOs>
>> <EntitlementTO>ROLE_ADMIN</EntitlementTO>
>> <EntitlementTO>ROLE_SUPERUSER</EntitlementTO>
>> </EntitlementTOs>
>>
>> Option 2:
>> <EntitlementTOs>
>> <EntitlementTO>
>> <name>ROLE_ADMIN</name>
>> </EntitlementTO>
>> <EntitlementTO>
>> <name> ROLE_SUPERUSER</name>
>> </EntitlementTO>
>> </EntitlementTOs>
>>
>> Option 1 matches more or less current marshaling. I personally would prefer
>> Option 2 because this would give us the opportunity to easily extend
>> EntitlementTO at a later point (if needed) without becoming incompatible
>> with previous version.
>>
>> WDYT?
>>
>> All of these changes will not apply to current Spring Controller/Services, but
>> only future CXF REST Service. So AuthenticationController will not be
>> renamed now, and responsetype of AuthenticationController will not
>> change. Changes only apply for new Service Interface and (Proxy)
>> Implementation.
>>
>> Best regards.
>> Jan
RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Jan Bernhardt <jb...@talend.com>.
> -----Original Message-----
> From: Andrei Shakirin [mailto:ashakirin@talend.com]
> Sent: Mittwoch, 23. Januar 2013 10:45
> To: dev@syncope.apache.org
> Subject: RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
>
> > +1
> > URL Location in Response header (as usual) and ResourceID (Long or
> > String) in HTTP response body.
>
> I would even put ResourceID to HTTP header as well.
> It is relative small and is kind of object metadata - that corresponds HTTP
> Header spec.
Agree.
>
> Cheers,
> Andrei.
>
> > -----Original Message-----
> > From: Jan Bernhardt [mailto:jbernhardt@talend.com]
> > Sent: Mittwoch, 23. Januar 2013 10:41
> > To: dev@syncope.apache.org
> > Subject: RE: [DISCUSS] New REST Service Interfaces -
> > ConfigurationService
> >
> > > -----Original Message-----
> > > From: Andrei Shakirin [mailto:ashakirin@talend.com]
> > > Sent: Mittwoch, 23. Januar 2013 10:38
> > > To: dev@syncope.apache.org
> > > Subject: RE: [DISCUSS] New REST Service Interfaces -
> > > ConfigurationService
> > >
> > > Hi,
> > >
> > > > I generally agree with the concept of returning created with the
> > > > location in create methods. The problem is though that our service
> > > > interface has no method to get the object based on the location.
> > >
> > > Pragmatic solution is returning URI as well as business object ID in
> > > Response object.
> > > In that case we avoid building URI / extracting ID from URI manually.
> >
> > +1
> > URL Location in Response header (as usual) and ResourceID (Long or
> > String) in HTTP response body.
> >
> > >
> > > Cheers,
> > > Andrei.
> > >
> > > > -----Original Message-----
> > > > From: Christian Schneider [mailto:cschneider111@gmail.com] On
> > > > Behalf Of Christian Schneider
> > > > Sent: Mittwoch, 23. Januar 2013 10:01
> > > > To: dev@syncope.apache.org
> > > > Subject: Re: [DISCUSS] New REST Service Interfaces -
> > > > ConfigurationService
> > > >
> > > > Hi Jan,
> > > >
> > > > I generally agree with the concept of returning created with the
> > > > location in create methods. The problem is though that our service
> > > > interface has no method to get the object based on the location.
> > > > So we either have to change our client and interface to work with
> > > > resource uris instead of ids or we have to return the id of the
> > > > object in the create method. So perhaps we can return the location
> > > > for true restful clients and the id in the entity of the response
> > > > for people using the
> > > interface.
> > > >
> > > > Christian
> > > >
> > > >
> > > > On 23.01.2013 09:06, Jan Bernhardt wrote:
> > > > > Hi Syncoper,
> > > > >
> > > > > here are the proposed changes for our Configuration Service:
> > > > >
> > > > > * Changing Create response type to javax.ws.rs.core.Response.
> > > > > This way
> > > > we can set response HTTP Status code (201 created) without
> > > > requiring HttpServletResponse as method parameter. Also according
> > > > to best RESTful practices instead of returning newly created
> > > > object directly, only URL for new Object (Configuration) will be
> returned.
> > > > Console does not even care about created response, thus network
> > > > traffic can be reduced, by not sending object (configuration). If
> > > > consumer does care about new object he can easily follow provided
> > > > URL (in response) and
> > > retrieve new object.
> > > > >
> > > > > * Changed ModelAndView response type to Set<ValidatorTO> /
> > > > Set<MailTemplateTO> and introduced wrapper TO classes for
> > > > ValidatorTO and MailTemplateTO.
> > > > >
> > > > > * Changed return type from update() and delete() to void, since
> > > > > console
> > > > does not even care about it, and I think this should be best
> > > > practice anyway, since consumer knows updates object already and
> > > > does not care about deleted ones, therefore there is no need to
> > > > send them over the
> > > network.
> > > > >
> > > > > Any objections?
> > > > >
> > > > > Best regards.
> > > > > Jan
> > > > >
RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Andrei Shakirin <as...@talend.com>.
> +1
> URL Location in Response header (as usual) and ResourceID (Long or String)
> in HTTP response body.
I would even put ResourceID to HTTP header as well.
It is relative small and is kind of object metadata - that corresponds HTTP Header spec.
Cheers,
Andrei.
> -----Original Message-----
> From: Jan Bernhardt [mailto:jbernhardt@talend.com]
> Sent: Mittwoch, 23. Januar 2013 10:41
> To: dev@syncope.apache.org
> Subject: RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
>
> > -----Original Message-----
> > From: Andrei Shakirin [mailto:ashakirin@talend.com]
> > Sent: Mittwoch, 23. Januar 2013 10:38
> > To: dev@syncope.apache.org
> > Subject: RE: [DISCUSS] New REST Service Interfaces -
> > ConfigurationService
> >
> > Hi,
> >
> > > I generally agree with the concept of returning created with the
> > > location in create methods. The problem is though that our service
> > > interface has no method to get the object based on the location.
> >
> > Pragmatic solution is returning URI as well as business object ID in
> > Response object.
> > In that case we avoid building URI / extracting ID from URI manually.
>
> +1
> URL Location in Response header (as usual) and ResourceID (Long or String)
> in HTTP response body.
>
> >
> > Cheers,
> > Andrei.
> >
> > > -----Original Message-----
> > > From: Christian Schneider [mailto:cschneider111@gmail.com] On Behalf
> > > Of Christian Schneider
> > > Sent: Mittwoch, 23. Januar 2013 10:01
> > > To: dev@syncope.apache.org
> > > Subject: Re: [DISCUSS] New REST Service Interfaces -
> > > ConfigurationService
> > >
> > > Hi Jan,
> > >
> > > I generally agree with the concept of returning created with the
> > > location in create methods. The problem is though that our service
> > > interface has no method to get the object based on the location.
> > > So we either have to change our client and interface to work with
> > > resource uris instead of ids or we have to return the id of the
> > > object in the create method. So perhaps we can return the location
> > > for true restful clients and the id in the entity of the response
> > > for people using the
> > interface.
> > >
> > > Christian
> > >
> > >
> > > On 23.01.2013 09:06, Jan Bernhardt wrote:
> > > > Hi Syncoper,
> > > >
> > > > here are the proposed changes for our Configuration Service:
> > > >
> > > > * Changing Create response type to javax.ws.rs.core.Response. This
> > > > way
> > > we can set response HTTP Status code (201 created) without requiring
> > > HttpServletResponse as method parameter. Also according to best
> > > RESTful practices instead of returning newly created object
> > > directly, only URL for new Object (Configuration) will be returned.
> > > Console does not even care about created response, thus network
> > > traffic can be reduced, by not sending object (configuration). If
> > > consumer does care about new object he can easily follow provided
> > > URL (in response) and
> > retrieve new object.
> > > >
> > > > * Changed ModelAndView response type to Set<ValidatorTO> /
> > > Set<MailTemplateTO> and introduced wrapper TO classes for
> > > ValidatorTO and MailTemplateTO.
> > > >
> > > > * Changed return type from update() and delete() to void, since
> > > > console
> > > does not even care about it, and I think this should be best
> > > practice anyway, since consumer knows updates object already and
> > > does not care about deleted ones, therefore there is no need to send
> > > them over the
> > network.
> > > >
> > > > Any objections?
> > > >
> > > > Best regards.
> > > > Jan
> > > >
RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Jan Bernhardt <jb...@talend.com>.
> -----Original Message-----
> From: Andrei Shakirin [mailto:ashakirin@talend.com]
> Sent: Mittwoch, 23. Januar 2013 10:38
> To: dev@syncope.apache.org
> Subject: RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
>
> Hi,
>
> > I generally agree with the concept of returning created with the
> > location in create methods. The problem is though that our service
> > interface has no method to get the object based on the location.
>
> Pragmatic solution is returning URI as well as business object ID in Response
> object.
> In that case we avoid building URI / extracting ID from URI manually.
+1
URL Location in Response header (as usual) and ResourceID (Long or String) in HTTP response body.
>
> Cheers,
> Andrei.
>
> > -----Original Message-----
> > From: Christian Schneider [mailto:cschneider111@gmail.com] On Behalf
> > Of Christian Schneider
> > Sent: Mittwoch, 23. Januar 2013 10:01
> > To: dev@syncope.apache.org
> > Subject: Re: [DISCUSS] New REST Service Interfaces -
> > ConfigurationService
> >
> > Hi Jan,
> >
> > I generally agree with the concept of returning created with the
> > location in create methods. The problem is though that our service
> > interface has no method to get the object based on the location.
> > So we either have to change our client and interface to work with
> > resource uris instead of ids or we have to return the id of the object
> > in the create method. So perhaps we can return the location for true
> > restful clients and the id in the entity of the response for people using the
> interface.
> >
> > Christian
> >
> >
> > On 23.01.2013 09:06, Jan Bernhardt wrote:
> > > Hi Syncoper,
> > >
> > > here are the proposed changes for our Configuration Service:
> > >
> > > * Changing Create response type to javax.ws.rs.core.Response. This
> > > way
> > we can set response HTTP Status code (201 created) without requiring
> > HttpServletResponse as method parameter. Also according to best
> > RESTful practices instead of returning newly created object directly,
> > only URL for new Object (Configuration) will be returned. Console does
> > not even care about created response, thus network traffic can be
> > reduced, by not sending object (configuration). If consumer does care
> > about new object he can easily follow provided URL (in response) and
> retrieve new object.
> > >
> > > * Changed ModelAndView response type to Set<ValidatorTO> /
> > Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO
> > and MailTemplateTO.
> > >
> > > * Changed return type from update() and delete() to void, since
> > > console
> > does not even care about it, and I think this should be best practice
> > anyway, since consumer knows updates object already and does not care
> > about deleted ones, therefore there is no need to send them over the
> network.
> > >
> > > Any objections?
> > >
> > > Best regards.
> > > Jan
> > >
RE: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Andrei Shakirin <as...@talend.com>.
Hi,
> I generally agree with the concept of returning created with the location in
> create methods. The problem is though that our service interface has no
> method to get the object based on the location.
Pragmatic solution is returning URI as well as business object ID in Response object.
In that case we avoid building URI / extracting ID from URI manually.
Cheers,
Andrei.
> -----Original Message-----
> From: Christian Schneider [mailto:cschneider111@gmail.com] On Behalf Of
> Christian Schneider
> Sent: Mittwoch, 23. Januar 2013 10:01
> To: dev@syncope.apache.org
> Subject: Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
>
> Hi Jan,
>
> I generally agree with the concept of returning created with the location in
> create methods. The problem is though that our service interface has no
> method to get the object based on the location.
> So we either have to change our client and interface to work with resource
> uris instead of ids or we have to return the id of the object in the create
> method. So perhaps we can return the location for true restful clients and
> the id in the entity of the response for people using the interface.
>
> Christian
>
>
> On 23.01.2013 09:06, Jan Bernhardt wrote:
> > Hi Syncoper,
> >
> > here are the proposed changes for our Configuration Service:
> >
> > * Changing Create response type to javax.ws.rs.core.Response. This way
> we can set response HTTP Status code (201 created) without requiring
> HttpServletResponse as method parameter. Also according to best RESTful
> practices instead of returning newly created object directly, only URL for new
> Object (Configuration) will be returned. Console does not even care about
> created response, thus network traffic can be reduced, by not sending
> object (configuration). If consumer does care about new object he can easily
> follow provided URL (in response) and retrieve new object.
> >
> > * Changed ModelAndView response type to Set<ValidatorTO> /
> Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO
> and MailTemplateTO.
> >
> > * Changed return type from update() and delete() to void, since console
> does not even care about it, and I think this should be best practice anyway,
> since consumer knows updates object already and does not care about
> deleted ones, therefore there is no need to send them over the network.
> >
> > Any objections?
> >
> > Best regards.
> > Jan
> >
Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Jan,
I generally agree with the concept of returning created with the
location in create methods. The problem is though that our service
interface has no method to get the object based on the location.
So we either have to change our client and interface to work with
resource uris instead of ids or we have to return the id of the object
in the create method. So perhaps we can return the location for true
restful clients and the id in the entity of the response for people
using the interface.
Christian
On 23.01.2013 09:06, Jan Bernhardt wrote:
> Hi Syncoper,
>
> here are the proposed changes for our Configuration Service:
>
> * Changing Create response type to javax.ws.rs.core.Response. This way we can set response HTTP Status code (201 created) without requiring HttpServletResponse as method parameter. Also according to best RESTful practices instead of returning newly created object directly, only URL for new Object (Configuration) will be returned. Console does not even care about created response, thus network traffic can be reduced, by not sending object (configuration). If consumer does care about new object he can easily follow provided URL (in response) and retrieve new object.
>
> * Changed ModelAndView response type to Set<ValidatorTO> / Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO and MailTemplateTO.
>
> * Changed return type from update() and delete() to void, since console does not even care about it, and I think this should be best practice anyway, since consumer knows updates object already and does not care about deleted ones, therefore there is no need to send them over the network.
>
> Any objections?
>
> Best regards.
> Jan
>