add a cookbook recipe with hints for how to build REST clients

mojolicious · Dec 21, 2016 · a3893b1 · a3893b1
1 parent 65eab88
commit a3893b1
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 0 deletions.
diff --git a/lib/Mojo/Transaction.pm b/lib/Mojo/Transaction.pm
@@ -144,13 +144,41 @@ Remote interface port.
 
 HTTP request, defaults to a L<Mojo::Message::Request> object.
 
+  # Access request information
+  my $method = $tx->req->method;
+  my $url    = $tx->req->url->to_abs;
+  my $info   = $tx->req->url->to_abs->userinfo;
+  my $host   = $tx->req->url->to_abs->host;
+  my $agent  = $tx->req->headers->user_agent;
+  my $custom = $tx->req->headers->header('Custom-Header');
+  my $bytes  = $tx->req->body;
+  my $str    = $tx->req->text;
+  my $hash   = $tx->req->params->to_hash;
+  my $all    = $tx->req->uploads;
+  my $value  = $tx->req->json;
+  my $foo    = $tx->req->json('/23/foo');
+  my $dom    = $tx->req->dom;
+  my $bar    = $tx->req->dom('div.bar')->first->text;
+
 =head2 res
 
   my $res = $tx->res;
   $tx     = $tx->res(Mojo::Message::Response->new);
 
 HTTP response, defaults to a L<Mojo::Message::Response> object.
 
+  # Access response information
+  my $code    = $tx->res->code;
+  my $message = $tx->res->message;
+  my $server  = $tx->res->headers->server;
+  my $custom  = $tx->res->headers->header('Custom-Header');
+  my $bytes   = $tx->res->body;
+  my $str     = $tx->res->text;
+  my $value   = $tx->res->json;
+  my $foo     = $tx->res->json('/23/foo');
+  my $dom     = $tx->res->dom;
+  my $bar     = $tx->res->dom('div.bar')->first->text;
+
 =head1 METHODS
 
 L<Mojo::Transaction> inherits all methods from L<Mojo::EventEmitter> and

diff --git a/lib/Mojolicious/Guides/Cookbook.pod b/lib/Mojolicious/Guides/Cookbook.pod
@@ -952,6 +952,32 @@ When we say L<Mojolicious> is a web framework we actually mean it, with
 L<Mojo::UserAgent> there's a full featured HTTP and WebSocket user agent built
 right in.
 
+=head2 REST web services
+
+Requests can be performed very comfortably with methods like
+L<Mojo::UserAgent/"get">, and always result in a L<Mojo::Transaction::HTTP>
+object, which has many wonderful attributes and methods. You can check for
+connection errors with L<Mojo::Transaction/"result">, or access HTTP request and
+response information directly through L<Mojo::Transaction/"req"> and
+L<Mojo::Transaction/"res">.
+
+  use Mojo::UserAgent;
+
+  # Request a resource and make sure there were no connection errors
+  my $ua = Mojo::UserAgent->new;
+  my $res = $ua->get(
+    'mojolicious.org/perldoc/Mojolicious' => {Accept => 'text/plain'})->result;
+
+  # Decide what to do with its representation
+  if    ($res->is_success)  { say $res->body }
+  elsif ($res->is_error)    { say $res->message }
+  elsif ($res->code == 301) { say $res->headers->location }
+  else                      { say 'Whatever...' }
+
+While methods like L<Mojo::Message::Response/"is_success"> and
+L<Mojo::Message::Response/"is_error"> serve as building blocks for more
+sophisticated REST clients.
+
 =head2 Web scraping
 
 Scraping information from websites has never been this much fun before. The