[Community] CM REST API naming

[Steve K Speicher]

mik.kersten at tasktop.com wrote on 04/15/2009 01:37:32 PM:

> Please respond to mik.kersten
> 
> Following up on today's discussion about the "URL Parameter" and 
"Namespaces
> Used" sections of http://open-services.net/bin/view/Main/CmRestApi here 
is a
> summary of I was proposing.  I realize that we agreed to proceed with 
this
> on the call, but wanted to elaborate on the justification.  I'm still
> feeling bad for commenting on this so late in the process. 
> 
Mik, thanks for the feedback, I'll try to address this and see how we can 
adapt at this point in the process.

> In addition to the relatively minor "os" name clash, it seems 
problematic to
> define multiple "os<mumble>" namespace without making "os" a proper
> namespace.  We would be using a hierarchical form of naming without 
making
> the prefix explicit.  It seems to me that we have a clear "oslc" acronym
> which will do a nice job of being the first segment of namespaces, mime
> types, as well as the corresponding type names in the implementations, 
some
> of which will become Java API and be frozen along with the spec.
> 
In the CM WG meeting, we discussed have global prefix of "oslc" and domain 
prefix of "oslc_cm" style for namespace prefixes and general convention.

> As we discussed on the call, there are benefits to using hierarchical
> naming, which is a common convention for both media types and XML 
namespaces
> (e.g., mpeg4-iod-xmt, vnd.oasis.opendocumen.chart, vnd.nokia.conml+xml, 
for
> more see http://www.iana.org/assignments/media-types/application/).  It
> seems less common to use hierarchical prefixes for URL parameters, where
> mixing namespaces is less common, so having it there seems optional, and
> there are benefits to a shorter form. 
> 
In the OSLC CM domain, we've focused on producing what is needed to 
support our specifications (initial set of scenarios) and not attempt to 
extract common patterns until other domain needs warrant it.  At the point 
when we determine it applies to other domains, we'll refactor to a more 
common prefix for URL parameters (or namespace).  Also, we were attempting 
to avoid namespace conflicts with these URL parameters as we see most 
service provider implementations will be adding these capabilities onto an 
existing implementation which could have these parameters already defined.

> Here's a pass through the naming: 
Let me propose a slight modification to these..

> * Parameter: "oslc.cm.query", may be better as just "cm.query" 
"oslc_cm.query"

No strong opinion on what you have with "oslc.cm.query" to what I propose, 
just trying to make the namespace prefix clear compared to a package 
naming convention.

> * Namespaces: "oslc.cm" and "oslc.disc"
"oslc_cm"  => http://open-services.net/cm/1.0
"oslc_disc" => http://open-services.net/discovery/1.0

Note: we avoid the dot ('.') in the prefix as we reuse these prefixes 
within our JSON resource formats and the dot is problematic as it has 
special semantics in JavaScript.

> * Media Type: "application/x-oslc.cm-request+xml" or
> "application/x-oslc.cm-changerequest+xml"
"application/x-oslc-cm-changerequest+xml"

As dot only appears to be used with the registered "vnd.*" mime types.
 
> Regarding the media types for application, it looks like the more recent
> names use the "." for hierarchical naming, but there are examples of 
both in
> the IANA listing.  Please note that I'm far from being an expert on 
media
> type naming, but after a quick glance at the other examples and RFC, it
> looks like "-" would be the convention for prefixing "request" while "."
> gets used for the hierarchical name (http://tools.ietf.org/html/rfc2046
). 
> 
> One final question that I have is regarding where we would like to end 
up
> with on the media type naming.  Do we want to stick with "x-oslc", or 
get
> into the "vnd" namespace like OSGI and OASIS have done
> (http://tools.ietf.org/html/rfc4288#section-3.2), or the top level like
> "atom"?

This brings up the issue of naming with IANA registration.  At this point 
in the process we do not plan to take these forward for registration like 
the examples you sighted.  Using the private extension "x-" convention and 
clearly specifying it's usage in our specifications, we have the 
flexibility of satisfying our scenarios without the need to register every 
mime type we introduce for a new resource format.

This follows some of the guidance in the Best Practices Guide (
http://tools.ietf.org/html/bcp13#section-3.1).

In my opinion, the specific format of the media type doesn't impact the 
specification much as it will be used by the lower-level protocol on 
content negotiation.  So it just needs to be unique and will be rarely 
read by a human other than by the programmer writing the initial 
integration at that level.  An end user would never see this embedded in a 
URL or elsewhere.

Please let me know if you think these should be changed to something 
different than what I proposed.  I plan to make a final pass at the bulk 
update of the specifications today so implementations can react 
accordingly.  Feel free to contact me directly if needed.

Thanks,
Steve Speicher | IBM Rational Software | (919) 254-0645



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/community_open-services.net/attachments/20090416/98d0ebb3/attachment-0003.html>