On Dec 30, 2009, at 4:56 PM, Adam Retter wrote:
> 2009/12/30 Paul Sandoz <Paul.Sandoz_at_sun.com>:
>>
>> On Dec 30, 2009, at 11:58 AM, Adam Retter wrote:
>>
>>>> Note that from the client perspective they should not really care
>>>> too
>>>> much
>>>> about the URIs and how to construct them as it is usually the
>>>> server that
>>>> informs the client on how to do that with links embedded in
>>>> representations.
>>>
>>> I am wondering in this case how the server would inform the client
>>> about the available URI's?
>>>
>>> Do you mean that http://www.company.com/rest/lodgement could
>>> return a
>>> list of URI's in some form?
>>
>> That is one way.
>>
>>
>>> If this is the case, then we really dont
>>> want this functionality. Our clients must already know their keys's
>>> for their lodgements.
>>>
>>
>> Or one could use a URI template:
>>
>> <keys template="http://www.company.com/rest/lodgement/{key}">
>>
>> <document template="http://www.company.com/rest/lodgement/{key}/
>> pdf">
>
> What are these URI templates? Can you give me some pointers to where I
> can find out more about them please?
>
See here:
http://bitworking.org/projects/URI-Templates/
JAX-RS supports a sub-set of the URI template syntax for values of
@Path for matching, plus a deviation for declaring regular expressions:
https://jsr311.dev.java.net/nonav/releases/1.1/javax/ws/rs/Path.html
and a sub-set for URI building:
https://jsr311.dev.java.net/nonav/releases/1.1/javax/ws/rs/core/UriBuilder.html
that only supports basic variable declarations of the form say "{foo}"
defined here:
http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html#var
It should be possible to update UriBuilder to support for the full URI
template syntax (as usual takes time to code!)
If you are using Jersey on the client side it is really easy to
process URI template conforming to the sub-set using UriBuilder.
>
>> Note that you could also use content negotiation on the first type
>> of URI to
>> return the XML with embedded PDF or the PDF document. And if
>> required you
>> could set of URI conneg so that:
>>
>> http://www.company.com/rest/lodgement/XYZ.pdf
>>
>> does the equivalent of a client using
>>
>> http://www.company.com/rest/lodgement/XYZ
>>
>> with an appropriate Accept header.
>>
>> IMHO that is a better, looser coupled, solution leaving the
>> possibility to
>> easily add further document formats if required in the future.
>
> Ah yes, Content Negotiation is a good idea :-) I guess thats with the
> @Consumes annotation?
>
Yes. And for URI conneg using the Jersey feature. See ResourceConfig:
https://jersey.dev.java.net/nonav/apidocs/latest/jersey/com/sun/jersey/api/core/ResourceConfig.html
> But actually I simplified a little bit in my examples.
>
> http://www.company.com/rest/lodgement/XYZ/pdf
>
> Doesnt actually return the PDF of the lodgement, it returns a custom
> XML document which embeds one or two PDF's, sometimes a lodgement has
> a related lodgement, the requirement I had was to return the pdf (or
> both if there is a related lodgement) from a single key.
>
> So I have modified my URI scheme to this -
>
> http://www.company.com/rest/lodgement/XYZ/pdfs (note the 's' on the
> end)
>
> This will return the associated pdf(s) embedded in a custom XML
> document. So /pdfs is a kinda operator really describing a processing
> action, not sure if my URI scheme reflects that or not? Or perhaps I
> should really be using the query string for that?
>
It is definitely a different resource. I think using a path segment
makes it more amenable with JAX-RS to using condition GETs and also
caching.
> I could still use content negotation in future with
> http://www.company.com/rest/lodgement/XYZ to return just the XML or
> PDF aspect :-)
>
I am not sure of your exact requirements, however, using mutlipart
MIME instead of embedding PDF in XML documents can be more efficient
in terms of transmission and processing on the client and server.
Paul.