.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTTP::Request::Common 3" .TH HTTP::Request::Common 3 2023-10-03 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 7 \& use HTTP::Request::Common; \& $ua = LWP::UserAgent\->new; \& $ua\->request(GET \*(Aqhttp://www.sn.no/\*(Aq); \& $ua\->request(POST \*(Aqhttp://somewhere/foo\*(Aq, foo => bar, bar => foo); \& $ua\->request(PATCH \*(Aqhttp://somewhere/foo\*(Aq, foo => bar, bar => foo); \& $ua\->request(PUT \*(Aqhttp://somewhere/foo\*(Aq, foo => bar, bar => foo); \& $ua\->request(OPTIONS \*(Aqhttp://somewhere/foo\*(Aq, foo => bar, bar => foo); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This module provides functions that return newly created \f(CW\*(C`HTTP::Request\*(C'\fR objects. These functions are usually more convenient to use than the standard \f(CW\*(C`HTTP::Request\*(C'\fR constructor for the most common requests. .PP Note that LWP::UserAgent has several convenience methods, including \&\f(CW\*(C`get\*(C'\fR, \f(CW\*(C`head\*(C'\fR, \f(CW\*(C`delete\*(C'\fR, \f(CW\*(C`post\*(C'\fR and \f(CW\*(C`put\*(C'\fR. .PP The following functions are provided: .ie n .IP "GET $url" 4 .el .IP "GET \f(CW$url\fR" 4 .IX Item "GET $url" .PD 0 .ie n .IP "GET $url, Header => Value,..." 4 .el .IP "GET \f(CW$url\fR, Header => Value,..." 4 .IX Item "GET $url, Header => Value,..." .PD The \f(CW\*(C`GET\*(C'\fR function returns an HTTP::Request object initialized with the "GET" method and the specified URL. It is roughly equivalent to the following call .Sp .Vb 4 \& HTTP::Request\->new( \& GET => $url, \& HTTP::Headers\->new(Header => Value,...), \& ) .Ve .Sp but is less cluttered. What is different is that a header named \&\f(CW\*(C`Content\*(C'\fR will initialize the content part of the request instead of setting a header field. Note that GET requests should normally not have a content, so this hack makes more sense for the \f(CW\*(C`PUT\*(C'\fR, \f(CW\*(C`PATCH\*(C'\fR and \f(CW\*(C`POST\*(C'\fR functions described below. .Sp The \f(CWget(...)\fR method of LWP::UserAgent exists as a shortcut for \&\f(CW\*(C`$ua\->request(GET ...)\*(C'\fR. .ie n .IP "HEAD $url" 4 .el .IP "HEAD \f(CW$url\fR" 4 .IX Item "HEAD $url" .PD 0 .ie n .IP "HEAD $url, Header => Value,..." 4 .el .IP "HEAD \f(CW$url\fR, Header => Value,..." 4 .IX Item "HEAD $url, Header => Value,..." .PD Like \fBGET()\fR but the method in the request is "HEAD". .Sp The \f(CWhead(...)\fR method of LWP::UserAgent exists as a shortcut for \&\f(CW\*(C`$ua\->request(HEAD ...)\*(C'\fR. .ie n .IP "DELETE $url" 4 .el .IP "DELETE \f(CW$url\fR" 4 .IX Item "DELETE $url" .PD 0 .ie n .IP "DELETE $url, Header => Value,..." 4 .el .IP "DELETE \f(CW$url\fR, Header => Value,..." 4 .IX Item "DELETE $url, Header => Value,..." .PD Like \f(CW\*(C`GET\*(C'\fR but the method in the request is \f(CW\*(C`DELETE\*(C'\fR. This function is not exported by default. .ie n .IP "PATCH $url" 4 .el .IP "PATCH \f(CW$url\fR" 4 .IX Item "PATCH $url" .PD 0 .ie n .IP "PATCH $url, Header => Value,..." 4 .el .IP "PATCH \f(CW$url\fR, Header => Value,..." 4 .IX Item "PATCH $url, Header => Value,..." .ie n .IP "PATCH $url, $form_ref, Header => Value,..." 4 .el .IP "PATCH \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4 .IX Item "PATCH $url, $form_ref, Header => Value,..." .ie n .IP "PATCH $url, Header => Value,..., Content => $form_ref" 4 .el .IP "PATCH \f(CW$url\fR, Header => Value,..., Content => \f(CW$form_ref\fR" 4 .IX Item "PATCH $url, Header => Value,..., Content => $form_ref" .ie n .IP "PATCH $url, Header => Value,..., Content => $content" 4 .el .IP "PATCH \f(CW$url\fR, Header => Value,..., Content => \f(CW$content\fR" 4 .IX Item "PATCH $url, Header => Value,..., Content => $content" .PD The same as \f(CW\*(C`POST\*(C'\fR below, but the method in the request is \f(CW\*(C`PATCH\*(C'\fR. .ie n .IP "PUT $url" 4 .el .IP "PUT \f(CW$url\fR" 4 .IX Item "PUT $url" .PD 0 .ie n .IP "PUT $url, Header => Value,..." 4 .el .IP "PUT \f(CW$url\fR, Header => Value,..." 4 .IX Item "PUT $url, Header => Value,..." .ie n .IP "PUT $url, $form_ref, Header => Value,..." 4 .el .IP "PUT \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4 .IX Item "PUT $url, $form_ref, Header => Value,..." .ie n .IP "PUT $url, Header => Value,..., Content => $form_ref" 4 .el .IP "PUT \f(CW$url\fR, Header => Value,..., Content => \f(CW$form_ref\fR" 4 .IX Item "PUT $url, Header => Value,..., Content => $form_ref" .ie n .IP "PUT $url, Header => Value,..., Content => $content" 4 .el .IP "PUT \f(CW$url\fR, Header => Value,..., Content => \f(CW$content\fR" 4 .IX Item "PUT $url, Header => Value,..., Content => $content" .PD The same as \f(CW\*(C`POST\*(C'\fR below, but the method in the request is \f(CW\*(C`PUT\*(C'\fR .ie n .IP "OPTIONS $url" 4 .el .IP "OPTIONS \f(CW$url\fR" 4 .IX Item "OPTIONS $url" .PD 0 .ie n .IP "OPTIONS $url, Header => Value,..." 4 .el .IP "OPTIONS \f(CW$url\fR, Header => Value,..." 4 .IX Item "OPTIONS $url, Header => Value,..." .ie n .IP "OPTIONS $url, $form_ref, Header => Value,..." 4 .el .IP "OPTIONS \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4 .IX Item "OPTIONS $url, $form_ref, Header => Value,..." .ie n .IP "OPTIONS $url, Header => Value,..., Content => $form_ref" 4 .el .IP "OPTIONS \f(CW$url\fR, Header => Value,..., Content => \f(CW$form_ref\fR" 4 .IX Item "OPTIONS $url, Header => Value,..., Content => $form_ref" .ie n .IP "OPTIONS $url, Header => Value,..., Content => $content" 4 .el .IP "OPTIONS \f(CW$url\fR, Header => Value,..., Content => \f(CW$content\fR" 4 .IX Item "OPTIONS $url, Header => Value,..., Content => $content" .PD The same as \f(CW\*(C`POST\*(C'\fR below, but the method in the request is \f(CW\*(C`OPTIONS\*(C'\fR .Sp This was added in version 6.21, so you should require that in your code: .Sp .Vb 1 \& use HTTP::Request::Common 6.21; .Ve .ie n .IP "POST $url" 4 .el .IP "POST \f(CW$url\fR" 4 .IX Item "POST $url" .PD 0 .ie n .IP "POST $url, Header => Value,..." 4 .el .IP "POST \f(CW$url\fR, Header => Value,..." 4 .IX Item "POST $url, Header => Value,..." .ie n .IP "POST $url, $form_ref, Header => Value,..." 4 .el .IP "POST \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4 .IX Item "POST $url, $form_ref, Header => Value,..." .ie n .IP "POST $url, Header => Value,..., Content => $form_ref" 4 .el .IP "POST \f(CW$url\fR, Header => Value,..., Content => \f(CW$form_ref\fR" 4 .IX Item "POST $url, Header => Value,..., Content => $form_ref" .ie n .IP "POST $url, Header => Value,..., Content => $content" 4 .el .IP "POST \f(CW$url\fR, Header => Value,..., Content => \f(CW$content\fR" 4 .IX Item "POST $url, Header => Value,..., Content => $content" .PD \&\f(CW\*(C`POST\*(C'\fR, \f(CW\*(C`PATCH\*(C'\fR and \f(CW\*(C`PUT\*(C'\fR all work with the same parameters. .Sp .Vb 4 \& %data = ( title => \*(Aqsomething\*(Aq, body => something else\*(Aq ); \& $ua = LWP::UserAgent\->new(); \& $request = HTTP::Request::Common::POST( $url, [ %data ] ); \& $response = $ua\->request($request); .Ve .Sp They take a second optional array or hash reference parameter \f(CW$form_ref\fR. The content can also be specified directly using the \f(CW\*(C`Content\*(C'\fR pseudo-header, and you may also provide the \f(CW$form_ref\fR this way. .Sp The \f(CW\*(C`Content\*(C'\fR pseudo-header steals a bit of the header field namespace as there is no way to directly specify a header that is actually called "Content". If you really need this you must update the request returned in a separate statement. .Sp The \f(CW$form_ref\fR argument can be used to pass key/value pairs for the form content. By default we will initialize a request using the \&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR content type. This means that you can emulate an HTML