[OSLC-CM] Fw: CM 1.0 comments and issues -- proposed response for review
Steve K Speicher
sspeiche at us.ibm.com
Wed Nov 25 10:26:23 EST 2009
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-0003.html>
More information about the Oslc-Cm
mailing list