Dave, I suggest something like the following:
An HTTP URI may contain an optional query string (see RFC 1738 or 3986) which is appended to some base URI and separated from it by a "?" character. The query string often has the syntax of a sequence of name-value pairs. The names that appear in the query string are referred to as query parameters. OSLC defines several standard query parameters, e.g. oslc.properties, that OSLC services MAY use. For example, when a base URI identifies some OSLC domain entity, such as a Requirement, the oslc.properties query parameter may be appended to it in order to select a subset of the domain entity's properties to be returned in the response to an HTTP GET request. [1] http://tools.ietf.org/html/rfc1738 [2] http://tools.ietf.org/html/rfc3986 Regards, ___________________________________________________________________________ Arthur Ryman, PhD, DE Chief Architect, Project and Portfolio Management IBM Software, Rational Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063 Twitter | Facebook | YouTube From: Dave <[email protected]> To: [email protected] Date: 03/17/2010 09:18 AM Subject: [oslc-core] Writing about forming URIs and query parameters Sent by: [email protected] Some of the text in the query resource and oslc.properties sections of the Core Spec DRAFT are a little confusing because I'm trying to constrain the way I write about URIs and resources. I'm trying to stick to the definitions in the glossary. I still have not found the correct language and I've been waiting until we merge in the Query Syntax stuff before fixing the prose. One thing I want to avoid is language that says things like "a resource supports query parameters" because that is not really consistent with the notions of URI and resource. Every different URI indicates a different resource and query parameters are part of the URI. So, for example, this URI: a) http://example.com/issues/issue501 Points to a completely different resource than this URI: b) http://example.com/issues/issue501?oslc.properties=dc:title In the example above, we have some data item "issue501" and the two resources above are two different ways to look, or two different views of that resource. The resource (b) is related to (a) because it is a subset of the property values of (a). Instead of using language like this: "resource URI supports an oslc.properties parameter that allows a client to return a subset of properties" I would prefer to use language more like this: "If you have a resource URI and you would like to obtain a subset of the property values in that resource, you can form URIs to subsets by adding the oslc.properties query parameter." And that is what I've been trying to do, but so far I have had limited success. Thoughts? Thanks, - Dave _______________________________________________ Oslc-Core mailing list [email protected] http://open-services.net/mailman/listinfo/oslc-core_open-services.net
