view release on metacpan or  search on metacpan

lib/Dancer2/Manual/Cookbook.pod  view on Meta::CPAN

=item * Serialize outgoing responses

When you return a data structure from a route, it will automatically
serialize it for you before returning it to the user.

=back

=head3 Configuring

In order to configure a serializer, you just need to pick which format
you want for encoding/decoding (e.g. L<JSON|Dancer2::Serializer::JSON>)
and set it up using the C<serializer> configuration keyword.

It is recommended to explicitly add it in the actual code instead of the
configuration file so it doesn't apply automatically to every app that
reads the configuration file (unless that's what you want):

     package MyApp;
     use Dancer2;
     set serializer => 'JSON'; # Dancer2::Serializer::JSON

     ...

=head3 Using

Now that we have a serializer set up, we can just return data structures:

     get '/' => sub {
         return { resources => \%resources };
     };

When we return this data structure, it will automatically be serialized
into JSON. No other code is necessary.

We also now receive requests in JSON:

     post '/:entity/:id' => sub {
         my $entity = route_parameters->get('entity');
         my $id     = route_parameters->get('id');

         # input which was sent serialized
         my $user = body_parameters->get('user');

         ...
     };

We can now make a serialized request:

     $ curl -X POST http://ourdomain/person/16 -d '{"user":"sawyer_x"}'

=head3 Supporting both serialized and non-serialized routes

Serializers are engines. They affect a Dancer Application, which means
that once you've set a serializer, B<all> routes within that package
will be serialized and deserialized. This is how the feature works.

As suggested above, if you would like to have both, you need to create
another application which will not be serialized.

A common usage for this is an API providing serialized endpoints (and
receiving serialized requests) and providing rendered pages.

     # MyApp.pm
     package MyApp;
     use Dancer2;

     # another useful feature:
     set auto_page => 1;

     get '/' => sub { template 'index' => {...} };

     # MyApp/API.pm
     package MyApp::API;
     use Dancer2;
     set serializer => 'JSON'; # or any other serializer

     get '/' => sub { +{ resources => \%resources, ... } };

     # user-specific routes, for example
     prefix '/users' => sub {
         get '/view'     => sub {...};
         get '/view/:id' => sub {...};
         put '/add'      => sub {...}; # automatically deserialized params
     };

     ...

Then those will be mounted together for a single app:

     # handler: app.pl:
     use MyApp;
     use MyApp::API;
     use Plack::Builder;

     builder {
         mount '/'    => MyApp->to_app;
         mount '/api' => MyApp::API->to_app;
     };

If you want use redirect from a mounted package to the application's root
URI, L<Dancer2::Plugin::RootURIFor> makes this possible:

    package OurWiki;
    use Dancer;
    use Dancer2::Plugin::RootURIFor;

    get '/:some_path' => sub {
        redirect root_uri_for('/');
    }

=head3 An example: Writing API interfaces

This example demonstrates an app that makes a request to a weather
API and then displays it dynamically in a web page.

Other than L<Dancer2> for defining routes, we will use L<HTTP::Tiny>
to make the weather API request, L<JSON> to decode it from JSON format,
and finally L<Path::Tiny> to provide a fully-qualified path to our
template engine.