On Dec 10, 2009, at 9:02 AM, Paul Sandoz wrote:
>
> On Dec 10, 2009, at 2:39 PM, Santiago Pericas-Geertsen wrote:
>
>> Paul,
>>
>>>> I've started a "List of Requirements" section in the wiki [1] based on this mail thread.
>>>>
>>>
>>> Great. I am not sure about requirement 1:
>>>
>>> 1) Meta-data about state transitions should not be part of a resource representation; instead it should be conveyed in HTTP
>>> headers or WADL documents, or both.
>>>
>>> Certain HTTP headers can be considered part of the representation i.e. representation == headers + entity.
>>
>> If by representation we include headers, then this requirement needs to be re-phrased. I think the main point is that entities should not be "artificially" extended to include state transitions information or other meta-data (as discussed earlier in this thread). I think Marc has a good point about this.
>>
>
> IIUC this captures the case when you have some existing entities that you cannot or do not want to modify?
>
Right. I think its fine (indeed desirable) for entities to contain links that represent application state transitions. I don't want to require them to do so though so we can support whatever entity formats an application uses. IOW a client needs to be able to support both links embedded within entities (for well designed hypermedia cognizant entities) and links in metadata (for use with existing entity formats).
>
>>>
>>> I suppose it depends on what you mean by meta-data, but typed links embedded in XML/JSON will contain data that the client can use to decide on whether to make a state transition (for example, HTML forms, plus this could get really interesting with RDF).
>>
>> Do you think typed links are enough to support HATEOAS?
>>
>
> I think they are mostly necessary (depending on how you specify things related to the media type), but are not sufficient if we want to improve the ability for machines communicate with each other (hence the reference to RDF, which is still being postulated as means for machines to better communicate). For now i think typed links are a good starting point to build upon.
>
I think typed links are the minimum required but, as evidenced by forms, a client needs more than just a link when an interaction requires the client to supply data rather than just get a link.
>
>>>
>>> I think Link headers and links embedded in entities need to be supported, and those should be sufficient to declare state transitions.
>>
>> Right. I think the point of (1) is that what can go in Link headers shouldn't be part of the entity.
>>
>
> Or vice versa, depending on the requirements?
>
> Using Link headers is a nice approach when one cannot or does not want to modify existing entities, or one does not want to place links in newly designed entities.
>
>
>>> WADLs role should be to help identify those links (reproducing data where required) in representations such that a client can use that at runtime or compile time to aid in the action of state transitions, but clients do not have to consume WADL if they do not want to.
Exactly. I think WADL could also be useful as a generic forms language to define the content and format of request entities as well as supplying information about the HTTP methods to use and additional link type metadata.
Marc.
>>
>> I agree. Do you want to take a stab at rephrasing the requirement?
>>
>
> OK. Before i do i would like to wait for a response from Marc.
>
> Paul.
>
>
>> -- Santiago
>>
>>>> On Dec 9, 2009, at 4:38 AM, Paul Sandoz wrote:
>>>>
>>>>>
>>>>> On Dec 8, 2009, at 10:56 PM, Marc Hadley wrote:
>>>>>
>>>>>> On Dec 8, 2009, at 2:34 PM, Marc Hadley wrote:
>>>>>>
>>>>>>> On Dec 8, 2009, at 2:08 PM, Santiago Pericas-Geertsen wrote:
>>>>>>>>
>>>>>>>> I want to make sure I understand and can capture all your points:
>>>>>>>>
>>>>>>>> 1) You *don't* think it's a good idea to extend resource representations to include additional meta-data (using Atom or otherwise) such as the following example from RESTfulie:
>>>>>>>>
>>>>>>>> <order>
>>>>>>>> <product>basic rails course</product>
>>>>>>>> <product>RESTful training</product>
>>>>>>>> <atom:link rel="refresh" href="
>>>>>>>> http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom
>>>>>>>> "/>
>>>>>>>> <atom:link rel="update" href="
>>>>>>>> http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom
>>>>>>>> "/>
>>>>>>>> <atom:link rel="pay" href="
>>>>>>>> http://www.caelum.com.br/orders/1/pay" xmlns:atom="http://www.w3.org/2005/Atom
>>>>>>>> "/>
>>>>>>>> <atom:link rel="cancel" href="
>>>>>>>> http://www.caelum.com.br/orders/1" xmlns:atom="http://www.w3.org/2005/Atom
>>>>>>>> "/>
>>>>>>>> </order>
>>>>>>>>
>>>>>>> Right. Up till now we've managed to keep JAX-RS at quite a meta-level and I don't think we should be in the business of defining what applications representations have to contain.
>>>>>>>
>>>>>>>>
>>>>>>>> 2) You'd prefer the use of HTTP headers to convey meta-data
>>>>>>>>
>>>>>>> Either headers or something like WADL that describes the links already available in representations. E.g. the information in the RESTfulie representation above could be split into data and metadata something like this:
>>>>>>>
>>>>>>> Link: <http://www.caelum.com.br/orders/1>; rel=refresh
>>>>>>> Link: <http://www.caelum.com.br/orders/1>; rel=update
>>>>>>> Link: <http://www.caelum.com.br/orders/1/pay>; rel=pay
>>>>>>> Link: <http://www.caelum.com.br/orders/1>; rel=cancel
>>>>>>>
>>>>>>> <order>
>>>>>>> <product>basic rails course</product>
>>>>>>> <product>RESTful training</product>
>>>>>>> </order>
>>>>>>>
>>>>>> BTW, I think it likely that existing representations could include URIs so its equally important to be able to ascribe state transition semantics to those without having to change the format of the representation.
>>>>>>
>>>>>
>>>>> Yes, the key is not to dictate a particular solution or "style" to the way state transition links are embedded in representations.
>>>>>
>>>>> However, i think It should be easy for the developer to create a particular style, or latch on to an existing style (the link header approach in this respect is not so intrusive).
>>>>>
>>>>> Paul.
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>>>>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>>>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>