I've recently joined this expert group and I'm going through the published draft proposal plus the hypermedia support proposal.
I generally like the direction and all of the proposed enhancements.
But I've several questions/comments on the various things that this JSR is introducing - I know I'm coming in cold, as there seems to have been many discussion email threads and voting etc. It will take me a while for me to go through all the discussion threads. Instead, I wanted to post my comments here - I fully realize that some of these may already have been discussed, and please point me to the right thread or outcome, as appropriate.
In eBay, we have realized the gaps in the 1.1 spec and have implemented many of the similar capabilities that are being proposed in the 2.0 spec and I can certainly share our real-world experience with this, as appropriate. A lot of the proposed capabilities are really needed for a production environment.
In this email, I'd like to summarize my comments/questions on the Handlers/Filters and hypermedia support.
Handlers and filters
* At the first glance, this seems to be confusing as well as incomplete. Disclaimer : it is possible that I didn't understand this fully
* As I understand it, Handlers don't seem really generic handlers, but specifically "filters" for Entity Providers, if you will. But they are also providers. It is confusing.
* The scenario that is not covered is handlers for wrapping around resource method invocation - This is needed, for example, to measure the time taken by the resource method itself (monitoring/metrics).
* Binding : The binding methods described are flexible, but in reality, only GlobalBinding is what is used in an operational environment. However, specific resources may indicate that certain filters don't apply to them - For example a SecurityFilter is always globally configured in an environment and some resource may specifically say, they want to turn security off, since they are not secure resources. How do you override or specify this exclusivity by certain resources ? Have you considered declaring all such filters/handlers in a config file at the container level, but individual resources either add or override certain filters via a Config init parameter or such ? Usability and practicality is very important to consider here.
* Binding : Why is it different on the client and server side ? Can we not use the same approach on both sides ?Hypermedia support
This is an important topic dear to my heart and to me hypermedia support should include
* Ability for the resource developers to specify which fields in their entities correspond to a resource (or sub resource), so that the container will automatically insert a link - whether for the self resource or some other resource. - Question is where in the response payload should the links be inserted and how minimally invasive can this be for resource developers - more on this later..
* Ability for the resource developer to specify to optionally include any meta data for how to change the representations - For example, if you have a purchase order resource, and in order to update the purchase order one must supply certain parameters or can only update certain fields, but not the others etc. This is important in the REST world, since there is no schema for the resource interface.
* Ability for the resource developers to specify that the media representation be converted into HTML (so user friendly rendering can happen)
* As an added step (arguably, nothing to do with hypermedia), automatically send the corresponding documentation, if the User-Agent is a browser. Take a look at this api -
https://api.mercadolibre.com/sites - Completely self navigable and very user friendly.
* Now coming back to where the links should be : I think that they can both be in headers (Link header) as well as in the payload under a special reserved field called "links" - But the payload links should be sent only if the User-Agent is a browser
* I like the @Linkable annotation with the optional ID specified, instead of the current proposed @Rel annotation, as described in the proposal.
thanks,
Sastry