Re: Service discovery redux - endpoint-based mechanisms

In our Jazz services we took an approach that was inspired by the 
OpenSearch spec, specifically their description document [1] that provides 
a service description for a search service. The description document tells 
a client, among other things how to construct a correct query, so that 
query parameters such as the "?query=" that are part of the current SPARQL 
protocol can be abstracted. The way the service protocol works in 
OpenSearch is something like this:

URL for service end-point is <http://example.com/search>

1. Client performs a GET on <http://example.com/search> itself. The 
service responds with the service description document (in XML, 
content-type application/opensearchdescription+xml).
2. Client looks for the URI template that best matches their needs which 
will be something like
    template="http://example.com/?q={searchTerms}&amp;pw={startPage?}"
3. The variables "searchTerms" and "startPage" are defined by the standard 
and so the client can substitute in the values provided by the user.
4. Client issues GET on the constructed URI.

We took this pattern and provided an RDF description document in the same 
vein; the basic protocol being that only GET is supported and the URI must 
be the unadorned service URI, a query uses the same URI but has the 
associated query parameters and the POST binding may or may not use the 
service URI but as the methods are distinguishable this works. 

[1] 
http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document



(Eric or anyone else, please feel free to push for query-based options, 
but I'm not including them in this message.

Here are the proposed service discovery mechanisms that are based on 
SPARQL endpoints. I've tried to include arguments for/against them where 
I've picked them up in the discussion so far. Please augment/correct as 
necessary.

Option 1 - HTTP-Header

Any GET or HEAD request on an endpoint would use an HTTP response header 
to provide a URL at which a service description for that endpoint can be 
found. Argument for: The response of any query issued against an 
endpoint will include a pointer to the service description. Headers are 
easy to include and consume. Argument against: This requires 2 requests 
to get the service description.


Option 2 - HTTP OPTIONS

Return a service description in response to an HTTP request on the 
endpoint that uses the HTTP OPTIONS verb. Argument for: Potentially 
revives the underutilized OPTIONS verb in an appropriate way. Argument 
against: OPTIONS is not commonly used and may be tough to implement in 
certain environments (e.g. XHR?) Also, OPTIONS may not have the proper 
cache semantics for service descriptions.


Option 7 - Conneg

An HTTP GET request on a SPARQL endpoint without any query parameters 
and specifying an RDF serialization in the Accept: header would return a 
service description for the endpoint. (Suggested in 
http://lists.w3.org/Archives/Public/public-rdf-dawg-comments/2009Jul/0005.html 

.) Argument for: Allows for endpoints that today return HTML query forms 
in response to a regular GET on the endpoint URI. Argument against: May 
be an abuse of content negotiation to return something which is not 
strictly an alternative representation of what would be shown in the 
HTML version. Content negotiation is not always easy to get right.


Option 8 - New protocol operation (?serviceDescription)

A request to a URI such as /endpoint/sparql?serviceDescription returns 
the service description. Argument for: Simple extension of SPARQL 
protocol that maps nicely to non-HTTP instantiations of the protocol. 
Easy to implement and invoke. A well-known pattern from Web Services 
stacks. Argument against: ?? Not sure, other than Steve is ok with it 
but not thrilled. :-)


Note, any of these could be combined with Orri's "compromise" proposal, 
in which the service description itself could optionally point to a 
graph that can be queried that contains the service description info.


Lee
Thanks,

Simon K. Johnston (skjohn@us.ibm.com) - STSM, Jazz Foundation Services
Mobile: +1 (919) 200-9973
Office: +1 (919) 595-0786 (tie-line: 268-6838)
Blog: http://www.ibm.com/developerworks/blogs/page/johnston