User:Zed

Name: Bill Zissimopoulos

Company: Evil Empire

Email: Afraid of spam harvesting, Steve knows my email :)

Since I did not want to modify any of your original content, I am putting some of my comments here:

• I like the overall approach of using HTTP as a CRUD style API and adding structure to URL's (e.g. for queries). This approach makes a lot of sense to me, because it makes data fragments into resources that can be treated in a REST-ful manner.
• Although this is not explicitly spelled out in the content that I have seen, I am assuming that you are observing proper HTTP semantics (and that POST is used for content insertion in particular).
  • SteveB: correct, we use both PUT and POST for content updates.  At the request dispatch level, both are treated the same b/c JavaScript libraries often don't provide a PUT verb in their implementations.
• Consider using the HTTP "Accept" header for specifying a non-XML encoding of the requested resource (e.g. for JSON: "Accept: application/x-json", or other suitable content type).
  • SteveB: good suggestion; although, I think this should complement the output=json query parameter, b/c the latter makes it easy to inspect results from a browser
  • UrsM: The idea with a REST API is that you can inspect and debug it very easily with 'curl' and a regular Web Browser.
    • Bill: Consider the following URL's:
      • http://server/data?select=/&output=json 
      • http://server/data?output=json&select=/ 
      • http://server/data?select=/ 
    • Are these resources different? The same? If you consider the first two the same, this scheme breaks simple caching (with keying based on the URL and header fields).
    • It seems to me that conceptually you are using the URL as both a resource name and a way of passing additional data about this particular request to the service (output=json). I find this asymmetrical.
• I rather dislike the use of parameters after the questionmark. Consider making everything after the questionmark an XPath query. [Actually perhaps the questionmark should really be a slash, although this would make it harder to implement. Rob Pike would certainly like you then: http://cm.bell-labs.com/cm/cs/doc/85/1-05.ps.gz]
  • SteveB: I was hoping to the fragment part for xpath query, so you could to http://server/service#xpath.  However, the fragment (#) is not sent by the browser :(
    • Bill: You are quite right.
  • SteveB: another point to consider, is that http://servier/service/foo?select=xpath is not the same as http://server/service/foo/bar; in the former, you are doing a query on a resource; on the latter, you're effectively querying another resource; imagine "foo" being a folder, we might be interested in only getting the folder size; however, if we specify an additional segment in the path, we really meant to retrieve a sub-resource; this is similar to query axises in xpath
    • Bill: As you well know I am not fond of complexity, which is why I suggested replacing the questionmark with a slash. You make a good point about the multiple axes. Furthermore keeping everything as a slash makes the whole data store appear as a giant XML document which may not be something you want. In my own implementation of a similar solution I also use the '?'.
    • BTW, to further clarify, I would propose a syntax of the form http://server/service/foo?xpath (i.e. no "select=")
• How do you return a set of nodes selected by an XPath query? Such a set is not XML (for example, it is lacking a root element or worse). In your "blueprint" example, an XPath query of "//feature" would return a set of 4 results, which are an XML forest, but not a tree. It seems you may need a resultset enveloping protocol (GData solves this by using Atom/RSS and also fixing the kind of things that can be returned).
  • SteveB: excellent observation; we currently only support one format for xml forrests over http and that is fixed size packets; for implementation might use multi-part responses or other framing protocols
    • Bill: What is the XML forest format that you use? Do you just dump the nodes one after the other and then set a content-type of text/plain? Other scheme?
    • I consider the "resultset enveloping protocol" the greatest headache with this approach.