Request Parameters and Uploads

Even though it is possible to expose different parts of an application using different URLs and paths, this usually is only enough for applications which model some kind of filesystem or repository. Applications which involve user input through forms, for example, need to be able to receive such input by other means, and this is where request parameters come in. For example, when a user fills out a form in a Web browser, the following happens:

  1. The browser collects the values in the form fields and puts them in a request as request parameters.
  2. The request is sent to the server environment and into the application.
  3. The application reads the field values using the WebStack API.

Parameter Origins

Request parameters exist in two forms:

One useful application of parameters transferred in request bodies is the sending or uploading of file contents through such parameters - this is described in "Request Body Parameters". Another way of uploading content in conjunction with the PUT request method is mentioned below.

WebStack API - Getting All Parameters

If the origin of the different parameters received in a request is not particularly interesting or important, WebStack provides a convenience method in transaction objects to get all known parameters from a request:

get_fields
This method returns a dictionary mapping field names to lists of values for all known parameters. Each value will be a Unicode object.
An optional encoding parameter may be used to assist the process of converting parameter values to Unicode objects - see "Request Body Parameters" and "Character Encodings" for more discussion of this parameter.
get_query_string
This method returns the part of the URL which contains parameter information. Such information will be "URL-encoded", meaning that certain characters will have the form %xx where xx is a two digit hexadecimal number referring to the byte value of the unencoded character - see "Character Encodings" for information on how byte values should be interpreted.

Generally, it is not recommended to just get all parameters since there may be some parameters from the request headers which have the same names as some other parameters from the request body. Consequently, confusion could arise about the significance of various parameter values.

Using PUT Requests to Upload Files

When handling requests in your application, instead of treating request as containers of parameters and using the WebStack API methods to access those parameters, you can instead choose to read directly from the data sent by the user and interpret that data in your own way. In most situations, this is not really necessary - those methods will decode request parameters (for example, form fields) in a way which is fairly convenient - but when files are being sent, and when the request method is specified as PUT, it is necessary to obtain the input stream from the request and to read the file contents from that stream.

WebStack API - Reading Directly from Requests

When the request does not contain standard form-encoded parameter information and instead contains the contents of an uploaded file, methods like get_fields and get_fields_from_body should be avoided and other methods in the transaction employed.

get_request_stream
This returns the input stream associated with the request. Reading from this will result in the request body being obtained as a plain Python string.
get_content_type
This returns a content type object (typically WebStack.Generic.ContentType) which describes the request body's contents.

The purpose and behaviour of PUT request methods is described in the HTTP specification.