Wolfram Research

FileDownloadResponse

Contributed by: Richard Hennigan (Wolfram Research)

Source Notebook

Generate an HTTP response that prompts the browser to download as a given file name

ResourceFunction["FileDownloadResponse"][expr,"filename"]

generates an HTTPResponse that informs the browser that the content should be downloaded as the given filename.

ResourceFunction["FileDownloadResponse"][expr,"filename",fmt]

uses fmt as the ExportForm.

ResourceFunction["FileDownloadResponse"][expr,"filename",fmt,metadata]

include metadata as part of the HTTPResponse.

Details and Options

ResourceFunction["FileDownloadResponse"] is usually stored in a CloudObject or specified as the result in an APIFunction or FormFunction.
The value for metadata in ResourceFunction["FileDownloadResponse"][expr,"filename",fmt,metadata] is an Association including the following possible elements:
"StatusCode" 200 HTTP status code
"ContentType" "text/html" MIME type for content
"Cookies" { } cookies to handle (using CookieFunction)
"Headers" { } a list of rules giving HTTP response headers
Properties of the resulting HTTPResponse object can be accessed using HTTPResponse[]["prop"].
Possible properties include all metadata items, together with:
"Body" response body as a string
"BodyByteArray" response body as a ByteArray object
"BodyBytes" response body as a list of byte values
"CharacterEncoding" character encoding in the response body (e.g. "UTF8")
"Properties" list of available properties
"StatusCodeDescription" plain text description of status code
ResourceFunction["FileDownloadResponse"] has the following options:
CharacterEncoding Automatic character encoding to apply to the response
CachePersistence Inherited how long to keep server‐side cached versions of computations that are done
"ContentType" Automatic specify a content‐type header
The setting CharacterEncoding"enc" specifies that the body in the resulting HTTPResponse[body,] should be encoded using the encoding enc before being returned from a server as an HTTP response.
The setting CharacterEncodingNone specifies that no change should be made to body before returning it.
The Automatic setting for the CharacterEncoding option will use an encoding given from the "ContentType" metadata property if it includes a charset specification (as in "text/html; charset=latin1"). It will also use an encoding from the "CharacterEncoding" metadata property. If no encoding is otherwise given, then the "UTF8" encoding is used for text-based MIME types and None for other MIME types.
If a specific encoding is given for the CharacterEncoding option, and the "ContentType" metadata property is a text-based MIME type, a charset specification will be automatically added to indicate the encoding to browsers.

Examples

Basic Examples

Generate an HTTPResponse:

In[1]:=
ResourceFunction[
 "FileDownloadResponse"][{{1, 2, 3}, {4, 5, 6}}, "download.csv"]
Out[1]=

The content disposition is set with the given file name:

In[2]:=
%["Headers"]
Out[2]=

Specify a format:

In[3]:=
ResourceFunction[
 "FileDownloadResponse"][{{1, 2, 3}, {4, 5, 6}}, "download.data", "Package"]
Out[3]=

Provide additional metadata for the HTTPResponse:

In[4]:=
ResourceFunction[
 "FileDownloadResponse"]["I'm a teapot", "download.txt", Automatic, <|
  "StatusCode" -> 418|>]
Out[4]=

Scope

The MIMEType is determined automatically from the file name when a format is not explicitly given:

In[5]:=
ResourceFunction["FileDownloadResponse"][{{1, 2, 3}, {4, 5, 6}}, "download.csv"]["ContentType"]
Out[5]=

It defaults to text if unknown:

In[6]:=
ResourceFunction["FileDownloadResponse"][{{1, 2, 3}, {4, 5, 6}}, "download"]["ContentType"]
Out[6]=

A format can be given explicitly to override the content type:

In[7]:=
ResourceFunction["FileDownloadResponse"][{{1, 2, 3}, {4, 5, 6}}, "download", "CSV"]["ContentType"]
Out[7]=

Specify custom headers:

In[8]:=
ResourceFunction[
 "FileDownloadResponse"]["Hello world", "hello.txt", Automatic, <|
  "Headers" -> {"My-Header" -> "Does it work?"}|>]
Out[8]=
In[9]:=
%["Headers"]
Out[9]=

Options

CharacterEncoding

Specify a character encoding:

In[10]:=
ResourceFunction["FileDownloadResponse"]["Hello world", "hello.txt", CharacterEncoding -> "UTF-8"]
Out[10]=
In[11]:=
ResourceFunction["FileDownloadResponse"]["Hello world", "hello.txt", CharacterEncoding -> "ASCII"]
Out[11]=

CachePersistence

Deploy a file download that is cached for 3 seconds:

In[12]:=
obj = CloudDeploy[
  Delayed[ResourceFunction["FileDownloadResponse"][
    DateString[{"Time", ".", "Millisecond"}], "date.txt", CachePersistence -> 3]]]
Out[12]=
In[13]:=
Table[Pause[1]; URLRead[obj, "Body"], 5]
Out[13]=

ContentType

Specify a MIMEType for the response:

In[14]:=
ResourceFunction["FileDownloadResponse"][Range[10], "download", "ContentType" -> "application/octet-stream"]
Out[14]=

Applications

Generate an HTTPResponse from a FormFunction for downloading an image:

In[15]:=
FormFunction[{"image" -> ExampleData["TestImage"][[All, 2]]},
 ResourceFunction["FileDownloadResponse"][
   ExampleData[{"TestImage", #image}], #image <> ".png"] &
 ]
Out[15]=

Deploy it to the cloud:

In[16]:=
CloudDeploy[%]
Out[16]=

Possible Issues

Specifying the content type in the metadata will override the format:

In[17]:=
ResourceFunction[
 "FileDownloadResponse"][{{1, 2, 3}, {4, 5, 6}}, "download.csv", "CSV", <|"ContentType" -> "text/html"|>]
Out[17]=

Providing a content disposition header in the metadata can override the given file name:

In[18]:=
ResourceFunction[
 "FileDownloadResponse"][{{1, 2, 3}, {4, 5, 6}}, "download.csv", "CSV", <|
  "Headers" -> {"content-disposition" -> "attachment; filename=override.csv"}|>]
Out[18]=
In[19]:=
%["Headers"]
Out[19]=

Resource History

See Also