[Community] CM REST API naming

[Mik Kersten]

These modifications sound like a very good compromise.  Thanks for the clear
explanations Steve.  

 

Mik 

 

--

Mik Kersten

CEO:  <http://tasktop.com/blog> http://tasktop.com/blog

Project Lead:  <http://eclipse.org/mylyn> http://eclipse.org/mylyn 

 

From: community-bounces at open-services.net
[mailto:community-bounces at open-services.net] On Behalf Of Steve K Speicher
Sent: Thursday, April 16, 2009 5:45 AM
To: community at open-services.net
Subject: Re: [Community] CM REST API naming

 


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>
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/>
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>
http://open-services.net/cm/1.0 
"oslc_disc" =>  <http://open-services.net/discovery/1.0>
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>
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>
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>
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/7b221f53/attachment-0003.html>