[OSLC-CM] Fw: CM 1.0 comments and issues -- proposed response for review

[Steve K Speicher]

OSLC CM WG,

Here's a draft response that I'd like to review at today's meeting.

Feel free to comment via email, I plan to respond after today's meeting.

- Steve

Martin Nally/Raleigh/IBM wrote on 11/23/2009 12:05:49 PM:

> Here are some comments on the CM 1.0 spec and suggestions of issues 
> to track for CM 2.0
> 
> Query string description
> 
> 
> The wording of this section could be improved. Instead of saying 
> “Request the Change Request resource at /bugs/bug123 and only the 
> properties of title and full owner details.” 
> We should say:
> “Request the resource that contains only the only the properties of 
> title and full owner details of the Change Request resource at 
/bugs/bug123.” 
> The point is that the URL (including the query string) identifies a 
> new resource. This resource has a relationship to the resource whose
> URL does not contain the query string.
> 

Agreed that the wording is improved.  Will target a future editor's update 
with the clarification.

> Namespaces
> 
> 
> In the example “/bugs/bug123?oslc_cm.properties=dc:title,dc:owner
> {*}”, dc appears to have meaning, but it is not clear what it means.
> Are we saying that in OSLC URLs of this form, dc always means “
> http://purl.org/dc/terms/”? This does not seem to me like a workable
> scheme. To make this work, we would need a way to register and 
> endless number of prefixes. Very few things on the web work this way
> – IANA is an exception, but it’s cumbersome. I think this design 
> needs to be revisited. The obvious alternative is to allow a URI in 
> place of a simple "word" and to eliminate the "word:word" form.
> 

We took a limited scope in reserving some namespace prefixes to 
simplify/shorten the URLs used.

These are defined at 
http://open-services.net/bin/view/Main/CmRestApiV1?#Namespaces_Used

We took a similar approach to what has been done in other specifications. 
I believe it was done in CQL http://www.loc.gov/standards/sru/index.html , 
though I can not locate the prefix namespace mapping table (though 
references to things like dc.title exist without a namespace definition).

> Managing multi-valued properties and resource links
> 
> This design is hard to understand. If I were to issue this request:
> 
> GET /records/12234-123344?oslc_cm.properties=blockedBy
> Accept: application/xml
> 
> I would get back this:
> 
> <oslc_cm:ChangeRequest>
>     <blockedBy oslc_cm:collref="/records/12234-123344/blockedBy"/>
> </oslc_cm:ChangeRequest>
> 
> This response contains no useful information except a “redirect” to 
> another URL. If I do a GET on that URL ("/records/12234-123344/
> blockedBy") I would get this:
> 
> <blockedBy oslc_cm:collref="/records/12234-123344/blockedBy">
>   <blockedBy rdf:resource="/links/1255-235411" 
> oslc_cm:label="Installation failures"/>
>   <blockedBy rdf:resource="/links/123455-2344" oslc_cm:label="DB 
> setup fails on 64 bit"/>
> </blockedBy>
> 
> I see no value in this “redirect”. It would have made much more 
> sense to return the blockedBy info directly on the first GET:
> 
> GET /records/12234-123344?oslc_cm.properties=blockedBy
> Accept: application/xml
> 
> With response:
> 
> <oslc_cm:ChangeRequest>
>   <blockedBy rdf:resource="/links/1255-235411" 
> oslc_cm:label="Installation failures"/>
>   <blockedBy rdf:resource="/links/123455-2344" oslc_cm:label="DB 
> setup fails on 64 bit"/>
> </oslc_cm:ChangeRequest>
> 
> Nothing would prevent us defining a POST against this URL to INSERT 
> entries, as defined in the current spec, although without a design 
> to do a corresponding DELETE and UPDATE, I think the value of this 
> POST is questionable.
> 

The choice for this approach was to handle a few scenarios:
1) By default, when doing a GET on a change request resource you get all 
the properties
If we were to provide an element for each referenced or multi-valued 
property, the response size grew significantly and the time to generate 
the response as well.
This level of indirection was introduced to limit the response, while 
giving the client a way to retrieve more.

There was also the issue of how to update this list of entries efficiently 
(remove, reorder, etc) which isn't addressed.  To remove an entry, a 
client does GET requesting either all or just the single property, all 
entries are returned, client prunes/updates the list, then PUTs back (note 
this is not prohibited by the spec, just an alternative is provided).


2) Ease of add to the collection of links/values
As you stated, this allows for the ease of adding to this collection via 
POST.  OSLC-CM WG is looking at improvements to this approach and looking 
at efforts in other domains on Collections and Links to assist.


> The text is unclear about what "/links/123455-2344" refers to, but 
> says it is a "link resouce". This appears to suggest that a GET on 
> this URL would take me not to the OSLC resource that is blocking the
> change, but some "link resource" that might in turn point to the 
> resource I'm interested in. I would not be in favor of this further 
> indirection, but in any case the spec needs to say what the design 
really is.
> 

The relative URL usage may have misled this meaning but comes from 
scenarios where we were representing our intra-repository structures and 
not necessarily cross-repository.
We intentionally left this referenced "rdf:resource" undefined as it could 
either be an internal "link resource" or a resource on a remote server.

> Relative URLs
> 
> Many of the URLs used in examples in the spec use relative URLs. 
> This is strange, because OSLC is about integration between 
> independent tools, which, lacking special magic, will have different
> hostnames/ports. The spec either needs to use absolute URLs in all 
> the examples, or explain how multiple, independent OSLC tools will 
> share a hostname/port.
> 

It is not intended to indicate any special magic, just an unfortunate 
shorthand that was preserved when developing the samples.  Will update in 
upcoming modification.

> Best regards, Martin
> 
> Martin Nally, IBM Fellow
> CTO and VP, IBM Rational
> tel: (949)544-4691

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-cm_open-services.net/attachments/20091125/1c0f6405/attachment-0001.html>