.\" Automatically generated by Pod::Man 4.14 (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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 3pm" .TH HTTP::Request::Common 3pm "2022-10-30" "perl v5.36.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 "NAME" HTTP::Request::Common \- Construct common HTTP::Request objects .SH "VERSION" .IX Header "VERSION" version 6.44 .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 "\s-1GET\s0 $url" 4 .el .IP "\s-1GET\s0 \f(CW$url\fR" 4 .IX Item "GET $url" .PD 0 .ie n .IP "\s-1GET\s0 $url, Header => Value,..." 4 .el .IP "\s-1GET\s0 \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 \*(L"\s-1GET\*(R"\s0 method and the specified \s-1URL.\s0 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 \s-1GET\s0 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(CW\*(C`get(...)\*(C'\fR method of LWP::UserAgent exists as a shortcut for \&\f(CW\*(C`$ua\->request(GET ...)\*(C'\fR. .ie n .IP "\s-1HEAD\s0 $url" 4 .el .IP "\s-1HEAD\s0 \f(CW$url\fR" 4 .IX Item "HEAD $url" .PD 0 .ie n .IP "\s-1HEAD\s0 $url, Header => Value,..." 4 .el .IP "\s-1HEAD\s0 \f(CW$url\fR, Header => Value,..." 4 .IX Item "HEAD $url, Header => Value,..." .PD Like \s-1\fBGET\s0()\fR but the method in the request is \*(L"\s-1HEAD\*(R".\s0 .Sp The \f(CW\*(C`head(...)\*(C'\fR method of LWP::UserAgent exists as a shortcut for \&\f(CW\*(C`$ua\->request(HEAD ...)\*(C'\fR. .ie n .IP "\s-1DELETE\s0 $url" 4 .el .IP "\s-1DELETE\s0 \f(CW$url\fR" 4 .IX Item "DELETE $url" .PD 0 .ie n .IP "\s-1DELETE\s0 $url, Header => Value,..." 4 .el .IP "\s-1DELETE\s0 \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 "\s-1PATCH\s0 $url" 4 .el .IP "\s-1PATCH\s0 \f(CW$url\fR" 4 .IX Item "PATCH $url" .PD 0 .ie n .IP "\s-1PATCH\s0 $url, Header => Value,..." 4 .el .IP "\s-1PATCH\s0 \f(CW$url\fR, Header => Value,..." 4 .IX Item "PATCH $url, Header => Value,..." .ie n .IP "\s-1PATCH\s0 $url, $form_ref, Header => Value,..." 4 .el .IP "\s-1PATCH\s0 \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4 .IX Item "PATCH $url, $form_ref, Header => Value,..." .ie n .IP "\s-1PATCH\s0 $url, Header => Value,..., Content => $form_ref" 4 .el .IP "\s-1PATCH\s0 \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 "\s-1PATCH\s0 $url, Header => Value,..., Content => $content" 4 .el .IP "\s-1PATCH\s0 \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 "\s-1PUT\s0 $url" 4 .el .IP "\s-1PUT\s0 \f(CW$url\fR" 4 .IX Item "PUT $url" .PD 0 .ie n .IP "\s-1PUT\s0 $url, Header => Value,..." 4 .el .IP "\s-1PUT\s0 \f(CW$url\fR, Header => Value,..." 4 .IX Item "PUT $url, Header => Value,..." .ie n .IP "\s-1PUT\s0 $url, $form_ref, Header => Value,..." 4 .el .IP "\s-1PUT\s0 \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4 .IX Item "PUT $url, $form_ref, Header => Value,..." .ie n .IP "\s-1PUT\s0 $url, Header => Value,..., Content => $form_ref" 4 .el .IP "\s-1PUT\s0 \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 "\s-1PUT\s0 $url, Header => Value,..., Content => $content" 4 .el .IP "\s-1PUT\s0 \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 "\s-1OPTIONS\s0 $url" 4 .el .IP "\s-1OPTIONS\s0 \f(CW$url\fR" 4 .IX Item "OPTIONS $url" .PD 0 .ie n .IP "\s-1OPTIONS\s0 $url, Header => Value,..." 4 .el .IP "\s-1OPTIONS\s0 \f(CW$url\fR, Header => Value,..." 4 .IX Item "OPTIONS $url, Header => Value,..." .ie n .IP "\s-1OPTIONS\s0 $url, $form_ref, Header => Value,..." 4 .el .IP "\s-1OPTIONS\s0 \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4 .IX Item "OPTIONS $url, $form_ref, Header => Value,..." .ie n .IP "\s-1OPTIONS\s0 $url, Header => Value,..., Content => $form_ref" 4 .el .IP "\s-1OPTIONS\s0 \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 "\s-1OPTIONS\s0 $url, Header => Value,..., Content => $content" 4 .el .IP "\s-1OPTIONS\s0 \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 "\s-1POST\s0 $url" 4 .el .IP "\s-1POST\s0 \f(CW$url\fR" 4 .IX Item "POST $url" .PD 0 .ie n .IP "\s-1POST\s0 $url, Header => Value,..." 4 .el .IP "\s-1POST\s0 \f(CW$url\fR, Header => Value,..." 4 .IX Item "POST $url, Header => Value,..." .ie n .IP "\s-1POST\s0 $url, $form_ref, Header => Value,..." 4 .el .IP "\s-1POST\s0 \f(CW$url\fR, \f(CW$form_ref\fR, Header => Value,..." 4 .IX Item "POST $url, $form_ref, Header => Value,..." .ie n .IP "\s-1POST\s0 $url, Header => Value,..., Content => $form_ref" 4 .el .IP "\s-1POST\s0 \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 "\s-1POST\s0 $url, Header => Value,..., Content => $content" 4 .el .IP "\s-1POST\s0 \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 \&\*(L"Content\*(R". 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 \s-1HTML\s0