1Dancer2::Plugin::REST(3U)ser Contributed Perl DocumentatiDoanncer2::Plugin::REST(3)
2
3
4

NAME

6       Dancer2::Plugin::REST - A plugin for writing RESTful apps with Dancer2
7

VERSION

9       version 1.02
10

SYNOPSIS

12           package MyWebService;
13
14           use Dancer2;
15           use Dancer2::Plugin::REST;
16
17           prepare_serializer_for_format;
18
19           get '/user/:id.:format' => sub {
20               User->find(params->{id});
21           };
22
23           get qr{^/user/(?<id>\d+)\.(?<format>\w+)} => sub {
24               User->find(captures->{id});
25           };
26
27           # curl http://mywebservice/user/42.json
28           { "id": 42, "name": "John Foo", email: "john.foo@example.com"}
29
30           # curl http://mywebservice/user/42.yml
31           --
32           id: 42
33           name: "John Foo"
34           email: "john.foo@example.com"
35

DESCRIPTION

37       This plugin helps you write a RESTful webservice with Dancer2.
38

CONFIGURATION

40   serializers
41       The default format serializer hash which maps a given ":format" to a
42       "Dancer2::Serializer::*" serializer. Unless overriden in the
43       configuration, it defaults to:
44
45           serializers:
46             json: JSON
47             yml:  YAML
48             dump: Dumper
49

KEYWORDS

51   prepare_serializer_for_format
52       When this pragma is used, a before filter is set by the plugin to
53       automatically change the serializer when a format is detected in the
54       URI.
55
56       That means that each route you define with a :format param or captures
57       token will trigger a serializer definition, if the format is known.
58
59       This lets you define all the REST actions you like as regular Dancer2
60       route handlers, without explicitly handling the outgoing data format.
61
62       Regexp routes will use the file-extension from captures->{'format'} to
63       determine the serialization format.
64
65   resource
66       This keyword lets you declare a resource your application will handle.
67
68           resource user =>
69               get    => sub { # return user where id = params->{id}   },
70               create => sub { # create a new user with params->{user} },
71               delete => sub { # delete user where id = params->{id}   },
72               update => sub { # update user with params->{user}       };
73
74           # this defines the following routes:
75           # GET /user/:id
76           # GET /user/:id.:format
77           # POST /user
78           # POST /user.:format
79           # DELETE /user/:id
80           # DELETE /user/:id.:format
81           # PUT /user/:id
82           # PUT /user/:id.:format
83
84   helpers
85       Helpers are available for all HTTP codes as recognized by
86       Dancer2::Core::HTTP:
87
88           status_100    status_continue
89           status_101    status_switching_protocols
90           status_102    status_processing
91
92           status_200    status_ok
93           status_201    status_created
94           status_202    status_accepted
95           status_203    status_non_authoritative_information
96           status_204    status_no_content
97           status_205    status_reset_content
98           status_206    status_partial_content
99           status_207    status_multi_status
100           status_208    status_already_reported
101
102           status_301    status_moved_permanently
103           status_302    status_found
104           status_303    status_see_other
105           status_304    status_not_modified
106           status_305    status_use_proxy
107           status_306    status_switch_proxy
108           status_307    status_temporary_redirect
109
110           status_400    status_bad_request
111           status_401    status_unauthorized
112           status_402    status_payment_required
113           status_403    status_forbidden
114           status_404    status_not_found
115           status_405    status_method_not_allowed
116           status_406    status_not_acceptable
117           status_407    status_proxy_authentication_required
118           status_408    status_request_timeout
119           status_409    status_conflict
120           status_410    status_gone
121           status_411    status_length_required
122           status_412    status_precondition_failed
123           status_413    status_request_entity_too_large
124           status_414    status_request_uri_too_long
125           status_415    status_unsupported_media_type
126           status_416    status_requested_range_not_satisfiable
127           status_417    status_expectation_failed
128           status_418    status_i_m_a_teapot
129           status_420    status_enhance_your_calm
130           status_422    status_unprocessable_entity
131           status_423    status_locked
132           status_424    status_failed_dependency
133           status_425    status_unordered_collection
134           status_426    status_upgrade_required
135           status_428    status_precondition_required
136           status_429    status_too_many_requests
137           status_431    status_request_header_fields_too_large
138           status_444    status_no_response
139           status_449    status_retry_with
140           status_450    status_blocked_by_windows_parental_controls
141           status_451    status_redirect
142           status_494    status_request_header_too_large
143           status_495    status_cert_error
144           status_496    status_no_cert
145           status_497    status_http_to_https
146           status_499    status_client_closed_request
147
148           status_500    status_error, status_internal_server_error
149           status_501    status_not_implemented
150           status_502    status_bad_gateway
151           status_503    status_service_unavailable
152           status_504    status_gateway_timeout
153           status_505    status_http_version_not_supported
154           status_506    status_variant_also_negotiates
155           status_507    status_insufficient_storage
156           status_508    status_loop_detected
157           status_509    status_bandwidth_limit_exceeded
158           status_510    status_not_extended
159           status_511    status_network_authentication_required
160           status_598    status_network_read_timeout_error
161           status_599    status_network_connect_timeout_error
162
163       All 1xx, 2xx and 3xx status helpers will set the response status to the
164       right value and serves its argument as the response, serialized.
165
166           status_ok({users => {...}});
167           # set status to 200, serves the serialized format of { users => {... } }
168
169           status_200({users => {...}});
170           # ditto
171
172           status_created({users => {...}});
173           # set status to 201, serves the serialized format of { users => {... } }
174
175       For error statuses ( 4xx and 5xx ), there is an additional dash of
176       syntaxic sugar: if the argument is a simple string, it'll be converted
177       to "{ error =" $error }>.
178
179           status_not_found({ error => "file $name not found" } );
180           # send 404 with serialization of { error => "file blah not found" }
181
182           status_not_found("file $name not found");
183           # ditto
184

LICENCE

186       This module is released under the same terms as Perl itself.
187

AUTHORS

189       This module has been written by Alexis Sukrieh "<sukria@sukria.net>"
190       and Franck Cuny.
191

SEE ALSO

193       Dancer2 <http://en.wikipedia.org/wiki/Representational_State_Transfer>
194

AUTHOR

196       Dancer Core Developers
197
199       This software is copyright (c) 2017, 2016, 2015, 2014, 2013, 2011, 2010
200       by Alexis Sukrieh.
201
202       This is free software; you can redistribute it and/or modify it under
203       the same terms as the Perl 5 programming language system itself.
204
205
206
207perl v5.36.0                      2023-01-20          Dancer2::Plugin::REST(3)
Impressum