#100 closed enhancement (fixed)

webapi -- final polishing

Reported by: zooko Owned by: warner
Priority: major Milestone: 0.5.0
Component: code-frontend-web Version: 0.4.0
Keywords: Cc:
Launchpad Bug:


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

Change History (9)

comment:1 Changed at 2007-08-13T17:15:58Z by zooko

  • Summary changed from webapi.txt -- final polishing to webapi -- final polishing

comment:2 Changed at 2007-08-14T00:31:10Z by warner

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

comment:3 Changed at 2007-08-14T18:54:18Z by warner

  • Component changed from code to code-frontend-web

comment:4 Changed at 2007-08-15T18:02:59Z by zooko

  • Owner changed from zooko to warner

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?

comment:5 Changed at 2007-08-15T18:17:39Z by 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

comment:6 Changed at 2007-08-15T19:10:08Z by 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.

comment:7 Changed at 2007-08-16T17:03:16Z by 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.

comment:8 Changed at 2007-08-16T17:47:23Z by 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.

comment:9 Changed at 2007-08-16T21:52:01Z by zooko

  • Resolution set to fixed
  • Status changed from new to closed
Note: See TracTickets for help on using tickets.