[OSLC-CM] CM 1.0 comments and issues
Martin Nally
nally at us.ibm.com
Thu Dec 3 10:39:52 EST 2009
Thanks, Steve. I think there are two topics we need to continue to work on
1) use of standard "namespace prefixes" in URLs
2) use of collection resources and link resources for multi-valued
properties
I think both of these designs would attract significant criticism if they
were exposed to a broader community of web specialists, such as those who
participate in the W3C and IETF communities. I myself don't support them
and don't want to be put in the position of defending them publically. I'm
pretty sure that if someone like Roy Fielding saw the design for 2), he
would have the same negative reaction he expressed when he saw similar
ideas in the CMIS standard
(http://roy.gbiv.com/untangled/2008/no-rest-in-cmis). The goal of our
designs is not to please Roy, but when someone that visible launches an
attack, it is not helpful for adoption.
Best regards, Martin
Martin Nally, IBM Fellow
CTO and VP, IBM Rational
tel: (949)544-4691
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Steve K Speicher/Raleigh/IBM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Martin Nally/Raleigh/IBM at IBMUS |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Cc: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|John Wiegand/Minneapolis/IBM at IBMUS, oslc-cm at open-services.net, Steve Abrams/Watson/IBM at IBMUS |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|11/25/2009 02:20 PM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Re: CM 1.0 comments and issues |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
Martin,
Thanks for the comments. I've included responses below that have been
discussed with the WG.
Regards,
Steve Speicher | IBM Rational Software | (919) 254-0645
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).
We agreed we should update with more description and sample where a
namespace definition is used.
> 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. We will update
in upcoming modification with absolute URLs.
> 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/20091203/d014c39d/attachment-0003.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: graycol.gif
Type: image/gif
Size: 105 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-cm_open-services.net/attachments/20091203/d014c39d/attachment.gif>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ecblank.gif
Type: image/gif
Size: 45 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-cm_open-services.net/attachments/20091203/d014c39d/attachment-0001.gif>
More information about the Oslc-Cm
mailing list