tahoe-lafs/trac-2024-07-25

webapi -- final polishing #100

New issue

Closed

opened 2007-08-13 17:14:26 +00:00 by zooko · 6 comments

zooko commented

2007-08-13 17:14:26 +00:00

Owner

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

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

tahoe-lafs added the

labels 2007-08-13 17:14:26 +00:00

tahoe-lafs added this to the 0.5.0 milestone 2007-08-13 17:14:26 +00:00

tahoe-lafs changed title from ~~webapi.txt -- final polishing~~ to webapi -- final polishing

2007-08-13 17:15:58 +00:00

warner commented

2007-08-14 00:31:10 +00:00

Author

Owner

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

tahoe-lafs added

code-frontend-web

and removed

code

labels 2007-08-14 18:54:18 +00:00

zooko commented

2007-08-15 18:02:59 +00:00

Author

Owner

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?

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 commented

2007-08-15 18:17:39 +00:00

Author

Owner

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

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 commented

2007-08-15 19:10:08 +00:00

Author

Owner

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.

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 commented

2007-08-16 17:03:16 +00:00

Author

Owner

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 commented

2007-08-16 17:47:23 +00:00

Author

Owner

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.

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.

tahoe-lafs added the

fixed

label 2007-08-16 21:52:01 +00:00

zooko closed this issue

2007-08-16 21:52:01 +00:00