webapi.rst fails to document /file/ and /named/ handlers #1662

New Issue

nejucomo · 2012-01-21T23:38:56Z

nejucomo commented

2012-01-21 23:38:56 +00:00

[This issue affects both the 1.9.0 and 1.9.1 source releases.]Note:

Symptom: I see browser requests for "GET /file/..." but when I grep for '/file' in webapi.rst I see no hits. I have also looked at every hit for "grep -i file" to verify this url path is not mentioned in webapi.rst.

Resolution: Update webapi.rst to describe /file/ urls.

Related Info: It looks as if /file/ may do something similar to /named/ or one may be an older backwards-compatible version of the same feature. If so, clearly document this. If the functional overlap is large and there's no compatibility requirement, we should file a new ticket to remove one of them. If the functionality partially overlaps but is distinct, webapi.rst should make the distinction clear.

Background: I am configuring access control policies based on HTTP method and path for a read-only gateway, so I want webapi.rst to tell me everything necessary for my usecase.

[This issue affects both the 1.9.0 and 1.9.1 source releases.]Note: Symptom: I see browser requests for "GET /file/..." but when I grep for '/file' in webapi.rst I see no hits. I have also looked at every hit for "grep -i file" to verify this url path is not mentioned in webapi.rst. Resolution: Update webapi.rst to describe /file/ urls. Related Info: It looks as if /file/ may do something similar to /named/ or one may be an older backwards-compatible version of the same feature. If so, clearly document this. If the functional overlap is large and there's no compatibility requirement, we should file a new ticket to remove one of them. If the functionality partially overlaps but is distinct, webapi.rst should make the distinction clear. Background: I am configuring access control policies based on HTTP method and path for a read-only gateway, so I want webapi.rst to tell me everything necessary for my usecase.

nejucomo added the

labels 2012-01-21 23:38:56 +00:00

nejucomo added this to the undecided milestone 2012-01-21 23:38:56 +00:00

nejucomo commented

2012-01-21 23:44:49 +00:00

In fact, as I continue reading webapi.rst I see the "Other Useful Pages" section begins by saying:

The portion of the web namespace that begins with "/uri" (and "/named") is
dedicated to giving users (both humans and programs) access to the Tahoe
virtual filesystem. The rest of the namespace provides status information
about the state of the Tahoe node.

This is misleading in the face of /file/ requests.

In fact, as I continue reading webapi.rst I see the "Other Useful Pages" section begins by saying: ``` The portion of the web namespace that begins with "/uri" (and "/named") is dedicated to giving users (both humans and programs) access to the Tahoe virtual filesystem. The rest of the namespace provides status information about the state of the Tahoe node. ``` This is misleading in the face of /file/ requests.

nejucomo commented

2012-01-22 01:43:47 +00:00

Analyzing the url namespace (see #1663) shows that /named and /file are handled by different instances of the same class. Unless that code switches logic based on this path segment, the two URL segments are synonymous.

If so, then in webapi.rst where /named is first mentioned, a short note saying "URLs may also use /file/... as a synonym for /named/... would close this ticket.

Analyzing the url namespace (see #1663) shows that `/named` and `/file` are handled by different instances of the same class. Unless that code switches logic based on this path segment, the two URL segments are synonymous. If so, then in webapi.rst where `/named` is first mentioned, a short note saying "URLs may also use `/file/...` as a synonym for `/named/...` would close this ticket.

tahoe-lafs added

documentation

and removed

unknown

labels 2012-01-22 06:13:50 +00:00

tahoe-lafs modified the milestone from undecided to 1.9.2

2012-01-22 06:13:50 +00:00

tahoe-lafs added

1.9.1

and removed

1.9.0

labels 2012-01-22 06:17:18 +00:00

tahoe-lafs changed title from ~~webapi.rst fails to mention /file/ handler.~~ to webapi.rst fails to document /file/ and /named/ handlers

2012-01-22 06:17:18 +00:00

tahoe-lafs modified the milestone from 1.9.2 to 1.10.0

2012-04-01 00:29:54 +00:00

marlowe commented

2012-04-01 03:22:41 +00:00

I can take this one if no one else wants it.

marlowe commented

2012-04-10 15:04:13 +00:00

Attachment ticket-1662.patch (833 bytes) added

Adds info on /file

**Attachment** ticket-1662.patch (833 bytes) added Adds info on /file

ticket-1662.patch

833 B

marlowe commented

2012-04-10 15:09:49 +00:00

This patch should resolve this ticket as /file and /named are synonyms. Thanks to Brian Warner for assistance with this ticket. The patch is also available as pull request 4 from antagonismorg on Github.

davidsarah commented

2012-04-10 16:28:00 +00:00

The WUI uses (that is, includes in directory listings) /file links but not /named links, I think. So should the [description in webapi.rst]source:docs/frontends/webapi.rst@5479#viewing-downloading-a-file be of /file with /named described as the synonym?

The WUI uses (that is, includes in directory listings) `/file` links but not `/named` links, I think. So should the [description in webapi.rst]source:docs/frontends/webapi.rst@5479#viewing-downloading-a-file be of `/file` with `/named` described as the synonym?

warner commented

2012-04-10 18:37:37 +00:00

Landed in changeset:589179cf. Thanks!

warner added the

fixed

label 2012-04-10 18:37:37 +00:00

warner closed this issue

2012-04-10 18:37:37 +00:00

tahoe-lafs modified the milestone from 1.10.0 to 1.9.2

2012-05-14 04:59:17 +00:00

Sign in to join this conversation.