NAME
REST::Utils - Utility functions for REST applications
SYNOPSIS
use REST::Utils qw( :all );
VERSION
This document describes REST::Utils Version 0.2
DESCRIPTION
This module contains some functions that are useful for implementing REST applications. They are designed to work with CGI.pm or something compatible with CGI.pm.
FUNCTIONS
The following functions are available. None of them are exported by default. You can give the tag :all to the use REST::Utils
statement to import all the functions at once.
Each function takes a CGI or compatible object as its first parameter.
content_prefs($cgi)
Returns a list of MIME media types given in the requests Accept
HTTP header sorted from most to least preferred.
Example:
my @types = content_prefs($cgi);
# @types = ('text/html'. 'text/plain', '*/*')
get_body($cgi)
This function will retrieve the body of an HTTP request regardless of the request method.
If the body is larger than CGI.pms' POST_MAX variable allows or if $ENV{CONTENT_LENGTH}
reports a bigger size than is actually available, get_body
will return undef.
If there is no body or if $ENV{CONTENT_LENGTH}
is undefined, it will return an empty string.
Otherwise it will return a scalar containing the body as a sequence of bytes up to the size of $ENV{CONTENT_LENGTH}
It is up to you to turn the bytes returned by get_body
into something useful.
media_type($cgi, \@types)
types
is a reference to a list of MIME media types. The function returns the member of the list most preferred by the requestor.
Example:
my $preferred = media_type($cgi, ['text/html', 'text/plain', '*/*']);
If the incoming request is a HEAD
or GET
, the function will return the member of the types
listref which is most preferred based on the Accept
HTTP headers sent by the requestor. If the requestor wants a type which is not on the list, the function will return undef
. (HINT: you can specify ' */*' to match every MIME media type.)
For POST
or PUT
requests, the function will compare the MIME media type in the Content-type
HTTP header provided by the requestor with the list and return that type if it matches a member of the list or undef
if it doesn't.
For other HTTP requests (such as DELETE
) this function will always return undef.
request_method($cgi)
This function returns the query's HTTP request method.
Example 1:
my $method = request_method($cgi);
Because many web sites don't allow the full set of HTTP methods needed for REST, you can "tunnel" methods through GET
or POST
requests in the following ways:
In the query with the _method
parameter. This will work even with POST
requests where parameters are usually passed in the request body.
Example 2:
http://localhost/index.cgi?_method=DELETE
Or with the X-HTTP-Method-Override
HTTP header.
Example 3:
X-HTTP-METHOD-OVERRIDE: PUT
if more than one of these are present, the HTTP header will override the query parameter, which will override the "real" method.
Any method can be tunneled through a POST
request. Only GET
and HEAD
can be tunneled through a GET
request. You cannot tunnel through a HEAD
, PUT
, DELETE
, or any other request. If an invalid tunnel is attempted, it will be ignored.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Rest::Utils
You can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
BUGS
There are no known problems with this module.
Please report any bugs or feature requests to bug-rest-Utils at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=REST-Utils. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
AUTHOR
Jaldhar H. Vyas, <jaldhar at braincells.com>
LICENSE AND COPYRIGHT
Copyright (c) 2010 Consolidated Braincells Inc. All rights reserved.
This distribution is free software; you can redistribute it and/or modify it under the terms of either:
a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or
b) the Artistic License version 2.0.
The full text of the license can be found in the LICENSE file included with this distribution.