webapi -- final polishing

[zooko]

Before releasing v0.5, I'd like to consider some changes to webapi.txt:

• Consider removing the name-based actions (I'm not sure it is a good idea, but I want to spend a few hours thinking it through.)
• If we're still providing named-based actions then we need to add the "?t=file" constraint on GET, at least. What about PUT?
• There are a couple of unfinished parts still, annotated with comments like "XXX specify this" in webapi.txt
• Check for bugs/inconsistencies/ambiguities in the current API and the documentation thereof.
• If anybody sees any editing improvements to make the webapi documentation clearer or more pleasurable to read that would be great.

See also ticket #98

[warner]

I've added #102 for the "replace / with ! in POST uris" issue.

[zooko]

Okay here's my current plan for webapi for v0.5 release (which will hopefully be today, or maybe tonight...)

• Forget about "removing name-based actions" from the webapi.

• Forget about adding the "?t=file" constraint, because the better way to avoid that ambiguity is to use the URI of the thing, in which case you already know definitely whether it is a file or a directory.

• I think I'll replace the TOCTTOU warning paragraph with the new one that I wrote in the new version of webapi.txt.

• It would be nice if Brian would look at the "XXX -- underspecified" notes in the current webapi.txt. Maybe it is okay to leave them underspecified for this release -- I'm not sure so I would like Brian to look at it.

• We need to either add the "?overwrite=" flag or else make it so that it does *not* overwrite, in the current version. (Because if it *does* overwrite there is no way to use it in a way to ensure not overwriting, but if it *doesn't* overwrite then you can simply delete-and-retry until you've successfully overwritten.)

• I'm going to replace "dirnode" with "directory".

Brian: what do you think?

[warner]

sounds good.

my action items:

• overwrite= : did we come to a consensus on what the default should be?
• review underspecified nodes, maybe address them, maybe not

[warner]

I've pushed changes to webapi.txt to address the underspecified sections.

I'm going to implement ?overwrite=false on the PUT command, making the default to be to accept overwrites without complaint. Note that HTTP's docs on PUT dictate a different return code for "you've just created a new resource" vs "you've just replaced an existing resource", which I think suggests that the HTTP authors thought that quietly-replacing was a fairly common operation.

[zooko]

A fellow on the #rest channel on IRC, nick of "jsled" suggested that we use accept headers instead of query params e.g. "?t=json" for content negotiation.

[warner]

yeah, that seems more RESTful.. I wonder how convenient it is for developers (i.e. does urllib make it easy to add request headers?). Also we'd need to define some MIME types.. x-allmydata/x-directory-json ?

Maybe we could declare that appending ?t=json to the URL is a shortcut/alias for adding Accept: x-allmydata/x-directory-json to the request headers, and thus allow both types of access.

The client would need to pay attention to the response's Content-Type: and make sure it matches what they expected.

Also, there are probably places where this could be used to tell the client whether they're visiting a directory node or a file node.