Plack::Middleware::REST - Route PSGI requests for RESTful web applications
# $get, $update, $delete, $create, $list, $patch, $app must be PSGI applications builder { enable 'REST', get => $get, # GET /{id} upsert => $update, # PUT /{id} delete => $delete, # DELETE /{id} create => $create, # POST / list => $list, # GET / patch => $patch, # PATCH /{id} head => 1, # HEAD /{$id} => $get, HEAD / => $list options => 1, # support OPTIONS requests pass_through => 1, # pass everything else to $app patch_types => ['text/plain']; # optional accepted patch types $app; };
Plack::Middleware::REST routes HTTP requests (given in PSGI request format) on the principles of Representational State Transfer (REST). In short, the application manages a set of resources with common base URL, each identified by its URL. One can retrieve, create, update, delete, list, and patch resources based on HTTP request methods.
Let's say an instance of Plack::Middleware::REST is mounted at the base URL http://example.org/item/. The following HTTP request types can be recognized, once they have been assigned:
http://example.org/item/
POST http://example.org/item/
Calls the PSGI application create to create a new resource with URL assigned by the application.
create
GET http://example.org/item/123
Calls the application get to retrieve an existing resource identified by http://example.org/item/123.
get
http://example.org/item/123
PUT http://example.org/item/123
Calls the PSGI application upsert to either update an existing resource identified by http://example.org/item/123 or to create a new resource with this URL. The application may reject updates and/or creation of new resources, acting like an update or insert method.
upsert
DELETE http://example.org/item/123
Calls the PSGI application delete to delete an existing resource identified by http://example.org/item/123.
delete
GET http://example.org/item/
Calls the PSGI application list to get a list of existing resources.
list
PATCH http://example.org/item/123
Calls the PSGI application patch to update an existing resource identified by http://example.org/item/123. The application may reject updates of resources.
patch
OPTIONS http://example.org/item/
Calls the PSGI application to return the allowed methods for the resource.
Other requests result either result in a PSGI response with error code 405 and a list of possible request types in the Accept header, or the request is passed to the underlying application in the middleware stack, if option pass_through is set.
Accept
pass_through
The options get, create, upsert, delete, list, patch can be set to PSGI applications to enable the corresponding REST request type. One can also use string aliases, including app to pass the request in the middleware stack:
app
builder { enable 'REST', get => 'app', # pass GET requests on resource to $wrapped create => $create, # pass POST to base URL to $create upsert => $update; # pass PUT requests on resources to $update pass_through => 0; # respond other requests with 405 $wrapped; };
By default (head => 1) the app configured to get and/or list resources are also assumed to handle HEAD requests. Setting this configuration to 0 will disallow HEAD requests. The special value auto will rewrite HEAD requests with Plack::Middleware::Head.
head => 1
0
auto
By default (options => 1) the app is configured to handle OPTIONS requests for a resource. Setting this configuration to 0 will dissallow OPTIONS requests.
options => 1
Respond to not allowed requests with HTTP 405. Enabled by default, but this may change in a future version of this module!
Optional array of acceptable patch document types for PATCH requests. Respond to unacceptable patch document types with HTTP 415.
Copyright 2014- Jakob Voß
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Jakob Voß and Chris Kirke
Plack::Middleware::REST::Util, included with Plack::Middleware::REST provides some utility methods to implement RESTful PSGI applications. The module may be removed in a future release.
See Plack::Middleware::Negotiate for content negotiation.
See Plack::Middleware::ETag for ETag generation.
Alternative CPAN modules with similar scope include Apache2::REST, REST::Utils, REST::Application, WWW::REST::Apid, WWW::REST::Simple, CGI::Application::Plugin::REST, and Plack::App::REST. Moreover there are general web application frameworks like Dancer/Dancer2, Mojolicious, and Catalyst. Maybe the number of such modules and frameworks is higher than the number of actual web APIs written in Perl. Who knows?
REST client modules at CPAN include REST::Client, Eixo::Rest, REST::Consumer, Net::Rest::Generic, LWP::Simple::REST, and WWW:.REST, Role::REST::Client, Rest::Client::Builder, MooseX::Role::REST::Consumer. Don't ask why.
To install Plack::Middleware::REST, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Plack::Middleware::REST
CPAN shell
perl -MCPAN -e shell install Plack::Middleware::REST
For more information on module installation, please visit the detailed CPAN module installation guide.