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

[nejucomo]

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

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]

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]

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.

[marlowe]

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

[marlowe]

Adds info on /file

[marlowe]

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]

The WUI uses (that is, includes in directory listings) /file links but not /named links, I think. So should the description in webapi.rst be of /file with /named described as the synonym?

[warner]

Landed in 589179cf. Thanks!