Using API/create workl item

I made a brief foray into RTC about 18 months ago, and then found it to be a little less than mature. I picked up again earlier this year, but then was stymied by the resource demands placed on our server. I updated the latter, and can now progress
The picture presented by RTC/Jazz is much better with version 3.0.1 than in my first view. I need to be able to use a range of extensions of the sort that were reasonably simple to implement with Clear Quest. Ive therefore dabbled with the API and found a range of examples from the Innovate workshops to draw on, as well as the SDK Wiki and the OSLC specifications and tutorials.
So much for context. This post is intended to note my experiences of RTC in early days, as they could be of use to developers and others. Ive been using the API with Java and Apache 4.1.3 http components from Windows with a Tomcat + Derby database implementation.
1) The examples presented at the workshops and in various notes about access via Form-based authentication were initially confusing. There appeared to be a couple of different approaches, which were mutually exclusive and did not translate simply into the present implementations interfacing needs. (This will doubtless be obvious to others, and may not be best practice). I found:
a. I should not use cookies explicitly to maintain session context through redirections
b. The URLs that should be addressed in requests to service discovery were less than obvious
c. There seems to be an amount of confusion about the media types that should be specified in requests as the OSLC standard ha matured.
d. There is much greater confusion about name prefixes and namespaces used to define the XML elements that must be sent or recovered.
2) Points 1c & d. appear to be significant problems. Its obvious that the developers are chasing moving targets (they may well be the forces behind some of the movement), but this does seem to be resulting in a rather fluid API. Tracking precisely what the current versions detailed needs are seems to be lacking in the public documents. I suggest that whats needed is to provide a clear snapshot of the naming conventions for any release.
3) Having found my way past the security on a protected document, it was then fairly easy to start navigating around the discover mechanism. I hit on one snag though, which was certainly of my own making. From the rootservices, I can find the Work Items service providers catalogue. The catalogue takes me to the services for listed projects. However, when I open the services.xml file I find a representation which is the same as the workshops documentation when I open with a browser, but different if I use my program.
4) Despite the problem in 3), I can progress, as I can alter my parsing to suit what Ive uncovered. I can work my way around work items etc simply enough.
5) I then reached my intended goal. I need to be able to build a new work item programmatically. Obviously I must know two things:
a. The service providers URL
b. The exact syntax of the (XML) request to define a submitted item.
Id like to think that these points should be clear from the documentation or examples. I ought to have the correct URL, but the responses from Tomcat are less than explicit: I get a 415 error with a standard HTML report. This really gives no information about whether Ive attacked the wrong service or my syntax is incorrect.
In respect of the syntactic requirements, these are much less than clear. Its apparent that the XML grammar has altered. Its also simple enough to find a current work item to compare against. The latter does not define whats actually required, although that should be largely able to be ascertained from a web form. OSLCs tutorial provides a nice example of using a resource shape, although I understand that this is still at the planning stage.
Is there a clear definition anywhere that someone could point to of the requirements for creating and submitting a new work item? This should be related to a specific version of RTC and detail not just the syntax and required fields, but also the requirements for other aspects, like the media type, content type and be a little clearer about the URL for submission. These problems would be significantly eased if messages other than Tomcats defaults were returned in responses.
Dave