Support attachment filename in Fili requests

[michael-mclawhorn]

Fili currently only sets download file names in the csv use case and doesn't allow any user specification of attachment format.

We should, via the format=FOO parameter support attachment filename specification.

Proposed contract change:
for jsonapi, json and csv (but not debug) allow parameterized arguments (similar to the parameterized metrics rfc) in the form of:
json[filename=foo].

Where the presence of filename will trigger/override the adding of the header:
"Content-Disposition: attachment; filename="foo""

format: csv by default will continue to add Content-Disposition with the generated filename, json, by default will continue to use the http default ('inline') behavior.

[cdeszaq]

I'm all for handling "download vs. not" uniformly across resources, but there are a few concerns I have with this:

1. What is the difference between a JSON response w/o a Content-Disposition header and one with the header? My understanding is that the presence of the header triggers the user agent (browser) to download the response as a file, rather than try to display it in the viewport.

   As such, would it make sense for the toggle to be "download or not" rather than "which filename would you like me to tell you this response is, and if I don't see a file name I won't tell the user agent to download this"?

2. Why does the client get to determine the file name?

   Not only would that mess with caching of the response, but it's also the server that is determining what's in the file and is best suited to give it an unambiguous name.

   Lastly, it's also super easy for the recipient of the file to change the name (though perhaps not the client application), so is this added complexity of accepting a user-specified file name worth the complexity? I'm guessing it is, but I've not seen (or don't recall) a convincing argument for it.

3. This seems to be very much in line with the existing HTTP Accept header, which exists to allow optimistic content negotiation between the client and the server, essentially providing a pathway for the client to ask for the resource in a particular format. With the general notion that query parameters override existing headers, we should make sure that any change we make moves towards allowing the format query param to behave the same way as the Accept header.

   I'm not asking for the full "format is just an override for Accept and we do the same thing for both inputs" change here, but only that we take the long-term view of where we want to be (ie. use the HTTP spec where possible) into account here.

4. Having the "default behavior" be different across the two different formats seems incongruous. Since we're looking to expand the behavior, is now the time to make the interface consistent and make a (backwards-compatible) switch in how response format is specified?

   I know versioning has come up as a concern in the past, and backwards compatibility in general is hard w/o versions being involved, so now may be a great time to move to versioning in the API. Stack Overflow has at least 1 post on the topic, and Git Hub API's content type-based versioning is a nice example as well. Stripe takes a very backwards-compatible approach to their versioning, but I'm not sure that would be highly applicable to Fili.

[michael-mclawhorn]

Revised proposal:

Add a fileName parameter to the API.

Existence of a filename parameter value forces the addition of a ContentDisposition Attachment header if one doesn't already exist. (e.g. default json)

Renaming downloaded files is not super convenient in the context of UI reporting interactions. Normally UIs can trigger download names on links but they can't if there is a cross-site difference between the API and the UI.

We've already had customers with large queries exceed the file name length limit in Excel in the case where the entire query is being spelled out in the file name.

At the heart of this is the navi (https://github.com/yahoo/navi) UI experience is customer reporting and custom reporting creates a demand for name management from reports.