paulb@335 | 1 | <?xml version="1.0" encoding="iso-8859-1"?> |
paulb@335 | 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
paulb@335 | 3 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@335 | 4 | <html xmlns="http://www.w3.org/1999/xhtml"> |
paulb@335 | 5 | <head> |
paulb@335 | 6 | <title>Request Parameters and Uploads</title> |
paulb@335 | 7 | <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
paulb@335 | 8 | <link href="styles.css" rel="stylesheet" type="text/css" /> |
paulb@335 | 9 | </head> |
paulb@335 | 10 | |
paulb@335 | 11 | <body> |
paulb@335 | 12 | <h1>Request Parameters and Uploads</h1> |
paulb@335 | 13 | |
paulb@335 | 14 | <p>Even though it is possible to expose different parts of an application |
paulb@335 | 15 | using different <a href="paths.html">URLs and paths</a>, this usually is only |
paulb@335 | 16 | enough for applications which model some kind of <a |
paulb@335 | 17 | href="paths-filesystem.html">filesystem</a> or repository. Applications which |
paulb@335 | 18 | involve user input through forms, for example, need to be able to receive |
paulb@335 | 19 | such input by other means, and this is where request parameters come in. For |
paulb@335 | 20 | example, when a user fills out a form in a Web browser, the following |
paulb@335 | 21 | happens:</p> |
paulb@335 | 22 | <ol> |
paulb@335 | 23 | <li>The browser collects the values in the form fields and puts them in a |
paulb@335 | 24 | request as request parameters.</li> |
paulb@335 | 25 | <li>The request is sent to the server environment and into the |
paulb@335 | 26 | application.</li> |
paulb@335 | 27 | <li>The application reads the field values using the WebStack API.</li> |
paulb@335 | 28 | </ol> |
paulb@335 | 29 | |
paulb@335 | 30 | <h2>Parameter Origins</h2> |
paulb@335 | 31 | |
paulb@335 | 32 | <p>Request parameters can originate from two sources:</p> |
paulb@335 | 33 | <ul> |
paulb@335 | 34 | <li><a href="parameters-headers.html">Request headers</a> - parameters are |
paulb@335 | 35 | found here when they are specified in the URL as a "query string".</li> |
paulb@335 | 36 | <li><a href="parameters-body.html">Request bodies</a> - parameters are |
paulb@335 | 37 | found here when the POST <a href="methods.html">request method</a> is |
paulb@335 | 38 | used.</li> |
paulb@335 | 39 | </ul> |
paulb@335 | 40 | |
paulb@346 | 41 | <p>One useful application of parameters transferred in request bodies is the |
paulb@346 | 42 | sending or uploading of file contents through such parameters - this is |
paulb@346 | 43 | described in "Request Body Parameters". Another way of uploading content in |
paulb@346 | 44 | conjunction with the <code>PUT</code> <a href="methods.html">request |
paulb@346 | 45 | method</a> is mentioned below.</p> |
paulb@346 | 46 | |
paulb@335 | 47 | <div class="WebStack"> |
paulb@335 | 48 | <h3>WebStack API - Getting All Parameters</h3> |
paulb@335 | 49 | |
paulb@335 | 50 | <p>If the origin of the different parameters received in a request is not |
paulb@335 | 51 | particularly interesting or important, WebStack provides a convenience method |
paulb@335 | 52 | in transaction objects to get all known parameters from a request:</p> |
paulb@335 | 53 | <dl> |
paulb@335 | 54 | <dt><code>get_fields</code></dt> |
paulb@335 | 55 | <dd>This method returns a dictionary mapping field names to lists of |
paulb@335 | 56 | values for all known parameters. Each value will be a Unicode |
paulb@335 | 57 | object.<br /> |
paulb@335 | 58 | An optional <code>encoding</code> parameter may be used to assist the |
paulb@335 | 59 | process of converting parameter values to Unicode objects - see <a |
paulb@335 | 60 | href="parameters-body.html">"Request Body Parameters"</a> and <a |
paulb@335 | 61 | href="encodings.html">"Character Encodings"</a> for more discussion of |
paulb@335 | 62 | this parameter.</dd> |
paulb@335 | 63 | </dl> |
paulb@335 | 64 | </div> |
paulb@335 | 65 | |
paulb@335 | 66 | <p>Generally, it is not recommended to just get all parameters since there |
paulb@335 | 67 | may be some parameters from the request headers which have the same names as |
paulb@335 | 68 | some other parameters from the request body. Consequently, confusion could |
paulb@335 | 69 | arise about the significance of various parameter values.</p> |
paulb@346 | 70 | |
paulb@346 | 71 | <h2>Using PUT Requests to Upload Files</h2> |
paulb@346 | 72 | |
paulb@346 | 73 | <p>When handling requests in your application, instead of treating request as |
paulb@346 | 74 | containers of parameters and using the WebStack API methods to access those |
paulb@346 | 75 | parameters, you can instead choose to read directly from the data sent by the |
paulb@346 | 76 | user and interpret that data in your own way. In most situations, this is not |
paulb@346 | 77 | really necessary - those methods will decode request parameters (for example, |
paulb@346 | 78 | form fields) in a way which is fairly convenient - but when files are being |
paulb@346 | 79 | sent, and when the <a href="methods.html">request method</a> is specified as |
paulb@346 | 80 | <code>PUT</code>, it is necessary to obtain the input stream from the request |
paulb@346 | 81 | and to read the file contents from that stream.</p> |
paulb@346 | 82 | |
paulb@346 | 83 | <div class="WebStack"> |
paulb@346 | 84 | <h3>WebStack API - Reading Directly from Requests</h3> |
paulb@346 | 85 | |
paulb@346 | 86 | <p>When the request does not contain standard form-encoded parameter |
paulb@346 | 87 | information and instead contains the contents of an uploaded file, methods |
paulb@346 | 88 | like <code>get_fields</code> and <code>get_fields_from_body</code> should be |
paulb@346 | 89 | avoided and other methods in the transaction employed.</p> |
paulb@346 | 90 | <dl> |
paulb@346 | 91 | <dt><code>get_request_stream</code></dt> |
paulb@346 | 92 | <dd>This returns the input stream associated with the request. Reading |
paulb@346 | 93 | from this will result in the request body being obtained as a plain |
paulb@346 | 94 | Python string.</dd> |
paulb@346 | 95 | <dt><code>get_content_type</code></dt> |
paulb@346 | 96 | <dd>This returns a content type object (typically |
paulb@346 | 97 | <code>WebStack.Generic.ContentType</code>) which describes the request |
paulb@346 | 98 | body's contents.</dd> |
paulb@346 | 99 | </dl> |
paulb@346 | 100 | </div> |
paulb@346 | 101 | |
paulb@346 | 102 | <p>The purpose and behaviour of <code>PUT</code> <a |
paulb@346 | 103 | href="methods.html">request methods</a> is described in the HTTP |
paulb@346 | 104 | specification.</p> |
paulb@335 | 105 | </body> |
paulb@335 | 106 | </html> |