Merge pull request #92 from libwww-perl/batch-example

Add a few examples and show usage of ->add_part() for batch requests

Author: oalders

Changes

@@ -1,6 +1,8 @@
 Revision history for HTTP-Message
 
 {{$NEXT}}
+    - Add some useful examples in HTTP::Request.
+      Batch requests are now explained.
 
 6.13      2017-06-20 01:07:03Z
     - Non-TRIAL release of changes found in 6.12

lib/HTTP/Request.pm

@@ -226,6 +226,91 @@ Method returning a textual representation of the request.
 
 =back
 
+=head1 EXAMPLES
+
+Creating requests to be sent with L<LWP::UserAgent> or others can be easy. Here
+are a few examples.
+
+=head2 Simple POST
+
+Here, we'll create a simple POST request that could be used to send JSON data
+to an endpoint.
+
+    #!/usr/bin/env perl
+
+    use strict;
+    use warnings;
+
+    use Encode qw(encode_utf8);
+    use HTTP::Request ();
+    use JSON::MaybeXS qw(encode_json);
+
+    my $url = 'https://www.example.com/api/user/123';
+    my $header = ['Content-Type' => 'application/json; charset=UTF-8'];
+    my $data = {foo => 'bar', baz => 'quux'};
+    my $encoded_data = encode_utf8(encode_json($data));
+
+    my $r = HTTP::Request->new('POST', $url, $header, $encoded_data);
+    # at this point, we could send it via LWP::UserAgent
+    # my $ua = LWP::UserAgent->new();
+    # my $res = $ua->request($r);
+
+=head2 Batch POST Request
+
+Some services, like Google, allow multiple requests to be sent in one batch.
+L<https://developers.google.com/drive/v3/web/batch> for example. Using the
+C<add_part> method from L<HTTP::Message> makes this simple.
+
+    #!/usr/bin/env perl
+
+    use strict;
+    use warnings;
+
+    use Encode qw(encode_utf8);
+    use HTTP::Request ();
+    use JSON::MaybeXS qw(encode_json);
+
+    my $auth_token = 'auth_token';
+    my $batch_url = 'https://www.googleapis.com/batch';
+    my $url = 'https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id';
+    my $url_no_email = 'https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false';
+
+    # generate a JSON post request for one of the batch entries
+    my $req1 = build_json_request($url, {
+        emailAddress => 'example@appsrocks.com',
+        role => "writer",
+        type => "user",
+    });
+
+    # generate a JSON post request for one of the batch entries
+    my $req2 = build_json_request($url_no_email, {
+        domain => "appsrocks.com",
+        role => "reader",
+        type => "domain",
+    });
+
+    # generate a multipart request to send all of the other requests
+    my $r = HTTP::Request->new('POST', $batch_url, [
+        'Accept-Encoding' => 'gzip',
+        # if we don't provide a boundary here, HTTP::Message will generate
+        # one for us. We could use UUID::uuid() here if we wanted.
+        'Content-Type' => 'multipart/mixed; boundary=END_OF_PART'
+    ]);
+
+    # add the two POST requests to the main request
+    $r->add_part($req1, $req2);
+    # at this point, we could send it via LWP::UserAgent
+    # my $ua = LWP::UserAgent->new();
+    # my $res = $ua->request($r);
+    exit();
+
+    sub build_json_request {
+        my ($url, $href) = @_;
+        my $header = ['Authorization' => "Bearer $auth_token", 'Content-Type' => 'application/json; charset=UTF-8'];
+        return HTTP::Request->new('POST', $url, $header, encode_utf8(encode_json($href)));
+    }
+
+
 =head1 SEE ALSO
 
 L<HTTP::Headers>, L<HTTP::Message>, L<HTTP::Request::Common>,
@@ -234,4 +319,3 @@ L<HTTP::Response>
 =cut
 
 #ABSTRACT: HTTP style request message
-

lib/HTTP/Request/Common.pm

@@ -215,7 +215,7 @@ sub form_data   # RFC1867
 		    # or perhaps a file in the /proc file system where
 		    # stat may return a 0 size even though reading it
 		    # will produce data.  So we cannot make
-		    # a Content-Length header.  
+		    # a Content-Length header.
 		    undef $length;
 		    last;
 		}
@@ -259,7 +259,7 @@ sub form_data   # RFC1867
 		}
 		if ($buflength) {
 		    defined $length && ($length -= $buflength);
-		    return $buf 
+		    return $buf
 	    	}
 	    }
 	};
@@ -317,9 +317,9 @@ __END__
 
 This module provides functions that return newly created C<HTTP::Request>
 objects.  These functions are usually more convenient to use than the
-standard C<HTTP::Request> constructor for the most common requests.  
+standard C<HTTP::Request> constructor for the most common requests.
 
-Note that L<LWP::UserAgent> has several convenience methods, including 
+Note that L<LWP::UserAgent> has several convenience methods, including
 C<get>, C<head>, C<delete>, C<post> and C<put>.
 
 The following functions are provided:
@@ -528,7 +528,9 @@ C<< $ua->request(POST ...) >>.
 
 L<HTTP::Request>, L<LWP::UserAgent>
 
+Also, there are some examples in L<HTTP::Request/"EXAMPLES"> that you might
+find useful. For example, batch requests are explained there.
+
 =cut
 
 #ABSTRACT: Construct common HTTP::Request objects
-