NAME

HTTP::Request::Common - Construct common HTTP::Request objects

SYNOPSIS

  use HTTP::Request::Common;
  $ua = LWP::UserAgent->new;
  $ua->request(GET 'http://www.sn.no/');
  $ua->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]);

DESCRIPTION

This module provide functions that return newly created HTTP::Request objects. These functions are usually more convenient to use than the standard HTTP::Request constructor for these common requests. The following functions are provided.

GET $url, Header => Value,...

The GET() function returns a HTTP::Request object initialized with the GET method and the specified URL. Without additional arguments it is exactly equivalent to the following call

  HTTP::Request->new(GET => $url)

but is less clutter. It also reads better when used together with the LWP::UserAgent->request() method:

  my $ua = new LWP::UserAgent;
  my $res = $ua->request(GET 'http://www.sn.no')
  if ($res->is_success) { ...

You can also initialize the header values in the request by specifying some key/value pairs as optional arguments. For instance:

  $ua->request(GET 'http://www.sn.no',
                   If_Match => 'foo',
                   From     => 'gisle@aas.no',
              );

A header key called 'Content' is special and when seen the value will initialize the content part of the request instead of setting a header.

HEAD $url, [Header => Value,...]

Like GET() but the method in the request is HEAD.

PUT $url, [Header => Value,...]

Like GET() but the method in the request is PUT.

POST $url, [$form_ref], [Header => Value,...]

This works mostly like GET() with POST as method, but this function also takes a second optional array or hash reference parameter ($form_ref). This argument can be used to pass key/value pairs for the form content. By default we will initialize a request using the application/x-www-form-urlencoded content type. This means that you can emulate a HTML <form> POSTing like this:

  POST 'http://www.perl.org/survey.cgi',
       [ name   => 'Gisle Aas',
         email  => 'gisle@aas.no',
         gender => 'M',
         born   => '1964',
         perc   => '3%',
       ];

This will create a HTTP::Request object that looks like this:

  POST http://www.perl.org/survey.cgi
  Content-Length: 66
  Content-Type: application/x-www-form-urlencoded

  name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25

The POST method also supports the multipart/form-data content used for Form-based File Upload as specified in RFC 1867. You trigger this content format by specifying a content type of 'form-data' as one of the request headers. If one of the values in the $form_ref is an array reference, then it is treated as a file part specification with the following interpretation:

  [ $file, $filename, Header => Value... ]

The first value in the array ($file) is the name of a file to open. This file will be read an its content placed in the request. The routine will croak if the file can't be opened. Use an undef as $file value if you want to specify the content directly. The $filename is the filename to report in the request. If this value is undefined, then the basename of the $file will be used. You can specify an empty string as $filename if you don't want any filename in the request.

Sending my ~/.profile to the survey used as example above can be achieved by this:

  POST 'http://www.perl.org/survey.cgi',
       Content_Type => 'form-data',
       Content      => [ name  => 'Gisle Aas',
                         email => 'gisle@aas.no',
                         gender => 'M',
                         born   => '1964',
                         init   => ["$ENV{HOME}/.profile"],
                       ]

This will create a HTTP::Request object that almost looks this (the boundary and the content of your ~/.profile is likely to be different):

  POST http://www.perl.org/survey.cgi
  Content-Length: 388
  Content-Type: multipart/form-data; boundary="6G+f"

  --6G+f
  Content-Disposition: form-data; name="name"
  
  Gisle Aas
  --6G+f
  Content-Disposition: form-data; name="email"
  
  gisle@aas.no
  --6G+f
  Content-Disposition: form-data; name="gender"
  
  M
  --6G+f
  Content-Disposition: form-data; name="born"
  
  1964
  --6G+f
  Content-Disposition: form-data; name="init"; filename=".profile"
  Content-Type: text/plain
  
  PATH=/local/perl/bin:$PATH
  export PATH

  --6G+f--

SEE ALSO

HTTP::Request, LWP::UserAgent

COPYRIGHT

Copyright 1997-1998, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.