We need a few special type of requests for testing/debugging purposes on swarm:
- raw: returns the raw content at the given hash
- hash: returns the hash and not the content
- list: returns the list of all the files in the manifest under the given path
- immutable: skip ENS resolving, only accept hashes
We have different kind of possible solutions on how to differentiate the requests to implement these special request types. These potential solutions all have their pros and cons.
We can just use request parameters (in the swarm namespace), e.g. swarm.list=true. The downside of this solution is that request parameters are generally not really used for changing the low-level behavior of the requests. Also these request parameters can get mixed up with web application level parameters, which can be confusing (although the namespace partly solves the problem).
On the upside, this solution is easy to use from the browser, and it can be linked in html too.
We can just use different url schemes for the different type of requests, e.g. bzzh:// for hash requests. The advantage is that it is clearly a low level solution, which does not get mixed up with web application level parameters.
It is also easy to use from the browser, it can be linked from html too.
The downside is that we would like to keep the number of url schemes minimal.
We could use the content-type or other request header fields to specify what kind of request do we want make. However, the semantics of content-type means a different thing: it just specifies the mime type of the data in the response body, but it does not change the contents of it. We could still use a custom request header field, but the disadvantage of that solution is that it is not easy to use from the browser, and there is no way to customize request headers from an html link.
We could say that there is no need to make any kind of special requests, we should just give back all the necessary information in different custom response headers. So if someone is interested in the hash response, just check the content of a custom response header field, it is always there. However, the downside again is usability from the browser: there is no way to make an html page in which you just have click on a link and see the hash or list or other special responses you need. This solution is not applicable for the immutable request, which just restricts the request, and does not add extra information to it.
It seems the URL scheme solution is the best among these, it works well for all the special request types we need, usable from the browser and html, and does not conflict with possible web apps.