lib/Catalyst/Request/REST.pm

   1 package Catalyst::Request::REST;
   2 use Moose;
   3
   4 use Catalyst::Utils;
   5 use namespace::autoclean;
   6
   7 extends 'Catalyst::Request';
   8 with 'Catalyst::TraitFor::Request::REST';
   9
  10 sub _insert_self_into {
  11   my ($class, $app_class ) = @_;
  12   # the fallback to $app_class is for the (rare and deprecated) case when
  13   # people are defining actions in MyApp.pm instead of in a controller.
  14   my $app = (blessed($app_class) && $app_class->can('_application'))
  15         ? $app_class->_application : Catalyst::Utils::class2appclass( $app_class ) || $app_class;
  16
  17   my $req_class = $app->request_class;
  18   return if $req_class->isa($class);
  19   if ($req_class eq 'Catalyst::Request') {
  20     $app->request_class($class);
  21   } else {
  22     die "$app has a custom request class $req_class, "
  23       . "which is not a $class; see Catalyst::Request::REST";
  24   }
  25 }
  26
  27 __PACKAGE__->meta->make_immutable;
  28 __END__
  29
  30 =head1 NAME
  31
  32 Catalyst::Request::REST - A REST-y subclass of Catalyst::Request
  33
  34 =head1 SYNOPSIS
  35
  36      if ( $c->request->accepts('application/json') ) {
  37          ...
  38      }
  39
  40      my $types = $c->request->accepted_content_types();
  41
  42 =head1 DESCRIPTION
  43
  44 This is a subclass of C<Catalyst::Request> that adds a few methods to
  45 the request object to faciliate writing REST-y code. Currently, these
  46 methods are all related to the content types accepted by the client.
  47
  48 Note that if you have a custom request class in your application, and it does
  49 not inherit from C<Catalyst::Request::REST>, your application will fail with an
  50 error indicating a conflict the first time it tries to use
  51 C<Catalyst::Request::REST>'s functionality.  To fix this error, make sure your
  52 custom request class inherits from C<Catalyst::Request::REST>.
  53
  54 =head1 METHODS
  55
  56 =over
  57
  58 =item data
  59
  60 If the request went through the Deserializer action, this method will
  61 return the deserialized data structure.
  62
  63 =item accepted_content_types
  64
  65 Returns an array reference of content types accepted by the
  66 client.
  67
  68 The list of types is created by looking at the following sources:
  69
  70 =over 8
  71
  72 =item * Content-type header
  73
  74 If this exists, this will always be the first type in the list.
  75
  76 =item * content-type parameter
  77
  78 If the request is a GET request and there is a "content-type"
  79 parameter in the query string, this will come before any types in the
  80 Accept header.
  81
  82 =item * Accept header
  83
  84 This will be parsed and the types found will be ordered by the
  85 relative quality specified for each type.
  86
  87 =back
  88
  89 If a type appears in more than one of these places, it is ordered based on
  90 where it is first found.
  91
  92 =item preferred_content_type
  93
  94 This returns the first content type found. It is shorthand for:
  95
  96   $request->accepted_content_types->[0]
  97
  98 =item accepts($type)
  99
 100 Given a content type, this returns true if the type is accepted.
 101
 102 Note that this does not do any wildcard expansion of types.
 103
 104 =back
 105
 106 =head1 AUTHORS
 107
 108 See L<Catalyst::Action::REST> for authors.
 109
 110 =head1 LICENSE
 111
 112 You may distribute this code under the same terms as Perl itself.
 113
 114 =cut