REST::Utils - Utility functions for REST applications
use REST::Utils qw( :all );
This document describes REST::Utils Version 0.6
This module contains some functions that are useful for implementing REST applications.
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.
use REST::Utils
Takes an arrayref of supported MIME types and finds the best match for all the media-ranges listed in $header. The value of $header must be a string that conforms to the format of the HTTP Accept: header. The value of @supported is a list of MIME types. If no type can be matched, undef is returned.
undef
Example:
print best_match(['application/xbel+xml', 'text/xml'], 'text/*;q=0.5,*/*; q=0.1'); # text/xml
This function takes a CGI or compatible object as its first parameter.
It 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.
$ENV{CONTENT_LENGTH}
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.
Find the best match for a given mime-type against a list of media_ranges that have already been parsed by parse_media_range(). Returns a list of the fitness value and the value of the 'q' quality parameter of the best match, or (-1, 0) if no match was found. Just as for quality_parsed(), @parsed_ranges must be a list of parsed media ranges.
This function takes a CGI or compatible object as its first parameter and a reference to a list of MIME media types as the second parameter. It returns the member of the list most preferred by the requestor.
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.)
HEAD
GET
types
Accept
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.
POST
PUT
Content-type
For other HTTP requests (such as DELETE) this function will always return an empty string.
DELETE
Carves up a media range and returns a list of the ($type, $subtype,\%params) where %params is a hash of all the parameters for the media range.
($type, $subtype,\%params)
For example, the media range 'application/*;q=0.5' would get parsed into:
('application', '*', { q => 0.5 })
In addition this function also guarantees that there is a value for 'q' in the %params hash, filling it in with a proper default if necessary.
Carves up a MIME type and returns a list of the ($type, $subtype, \%params) where %params is a hash of all the parameters for the media range.
For example, the media range 'application/xhtml;q=0.5' would get parsed into:
('application', 'xhtml', { q => 0.5 })
Returns the quality 'q' of a MIME type when compared against the media-ranges in $ranges. For example:
print quality('text/html', 'text/*;q=0.3, text/html;q=0.7, text/html;level # 0.7
Find the best match for a given MIME type against a list of media_ranges that have already been parsed by parse_media_range(). Returns the 'q' quality parameter of the best match, 0 if no match was found. This function behaves the same as quality() except that @parsed_ranges must be a list of parsed media ranges.
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.
_method
Example 2:
http://localhost/index.cgi?_method=DELETE
Or with the X-HTTP-Method-Override HTTP header.
X-HTTP-Method-Override
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.
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
http://rt.cpan.org/NoAuth/Bugs.html?Dist=REST-Utils
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/REST-Utils
CPAN Ratings
http://cpanratings.perl.org/d/REST-Utils
Search CPAN
http://search.cpan.org/dist/REST-Utils/
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.
bug-rest-Utils at rt.cpan.org
MIME type parsing code borrowed from MIMEParser.pm by: Joe Gregorio joe at bitworking.org Stanis Trendelenburg stanis.trendelenburg at gmail.com (http://code.google.com/p/mimeparse/)
joe at bitworking.org
stanis.trendelenburg at gmail.com
Jaldhar H. Vyas, <jaldhar at braincells.com>
<jaldhar at braincells.com>
Copyright (c) 2012 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.
To install REST::Utils, copy and paste the appropriate command in to your terminal.
cpanm
cpanm REST::Utils
CPAN shell
perl -MCPAN -e shell install REST::Utils
For more information on module installation, please visit the detailed CPAN module installation guide.