[Community] CM REST API naming

[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.  

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.

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.  

Here's a pass through the naming: 
* Parameter: "oslc.cm.query", may be better as just "cm.query" 
* Namespaces: "oslc.cm" and "oslc.disc"
* Media Type: "application/x-oslc.cm-request+xml" or
"application/x-oslc.cm-changerequest+xml"

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"?

Mik 

--
Mik Kersten
CEO: http://tasktop.com/blog
Project Lead: http://eclipse.org/mylyn