dzil stuff

MANIFEST

@@ -1,18 +1,19 @@
-Build.PL
 Changes
 INSTALL
 LICENSE
 MANIFEST
 META.json
 META.yml
+Makefile.PL
 README
 README.mkdn
 SIGNATURE
 cpanfile
 doap.xml
 lib/Dancer2/Plugin/REST.pm
 t/00-compile.t
-t/000-report-versions-tiny.t
+t/00-report-prereqs.dd
+t/00-report-prereqs.t
 t/02_prepare_serializer_for_format.t
 t/03_resource.t
 t/04_helpers.t

README

@@ -1,5 +1,129 @@
-Dancer::Plugin::REST
+=pod
 
-A Dancer plugin to transform your Dancer app in a RESTful 
-webservice.
+
+=head1 SYNOPSYS
+
+    package MyWebService;
+
+    use Dancer2;
+    use Dancer2::Plugin::REST;
+
+    prepare_serializer_for_format;
+
+    get '/user/:id.:format' => sub {
+        User->find(params->{id});
+    };
+
+    get qr{^/user/(?<id>\d+)\.(?<format>\w+)} => sub {
+        User->find(captures->{id});
+    };
+
+    # curl http://mywebservice/user/42.json
+    { "id": 42, "name": "John Foo", email: "john.foo@example.com"}
+
+    # curl http://mywebservice/user/42.yml
+    --
+    id: 42
+    name: "John Foo"
+    email: "john.foo@example.com"
+
+=head1 DESCRIPTION
+
+This plugin helps you write a RESTful webservice with Dancer2.
+
+=head1 CONFIGURATION
+
+=head2 serializers
+
+The default format serializer hash which maps a given C<:format> to 
+a C<Dancer2::Serializer::*> serializer. Unless overriden in the 
+configuration, it defaults to:
+
+    serializers:
+      json: JSON
+      yml:  YAML
+      dump: Dumper
+
+=head1 KEYWORDS
+
+=head2 prepare_serializer_for_format
+
+When this pragma is used, a before filter is set by the plugin to automatically
+change the serializer when a format is detected in the URI.
+
+That means that each route you define with a B<:format> param or captures token 
+will trigger a serializer definition, if the format is known.
+
+This lets you define all the REST actions you like as regular Dancer2 route
+handlers, without explicitly handling the outgoing data format.
+
+Regexp routes will use the file-extension from captures->{'format'} to determine
+the serialization format.
+
+=head2 resource
+
+This keyword lets you declare a resource your application will handle.
+
+    resource user =>
+        get    => sub { # return user where id = params->{id}   },
+        create => sub { # create a new user with params->{user} },
+        delete => sub { # delete user where id = params->{id}   },
+        update => sub { # update user with params->{user}       };
+
+    # this defines the following routes:
+    # GET /user/:id
+    # GET /user/:id.:format
+    # POST /user
+    # POST /user.:format
+    # DELETE /user/:id
+    # DELETE /user/:id.:format
+    # PUT /user/:id
+    # PUT /user/:id.:format
+
+=head2 helpers
+
+Some helpers are available. This helper will set an appropriate HTTP status for you.
+
+=head3 status_ok
+
+    status_ok({users => {...}});
+
+Set the HTTP status to 200
+
+=head3 status_created
+
+    status_created({users => {...}});
+
+Set the HTTP status to 201
+
+=head3 status_accepted
+
+    status_accepted({users => {...}});
+
+Set the HTTP status to 202
+
+=head3 status_bad_request
+
+    status_bad_request("user foo can't be found");
+
+Set the HTTP status to 400. This function as for argument a scalar that will be used under the key B<error>.
+
+=head3 status_not_found
+
+    status_not_found("users doesn't exists");
+
+Set the HTTP status to 404. This function as for argument a scalar that will be used under the key B<error>.
+
+=head1 LICENCE
+
+This module is released under the same terms as Perl itself.
+
+=head1 AUTHORS
+
+This module has been written by Alexis Sukrieh C<< <sukria@sukria.net> >> and Franck
+Cuny.
+
+=head1 SEE ALSO
+
+L<Dancer2> L<http://en.wikipedia.org/wiki/Representational_State_Transfer>