/ 
REST-Utils-0.5
River stage one • 3 direct dependents • 3 total dependents
/ REST::Utils

NAME

REST::Utils - Utility functions for REST applications

SYNOPSIS

use REST::Utils qw( :all );

VERSION

This document describes REST::Utils Version 0.5

DESCRIPTION

This module contains some functions that are useful for implementing REST applications.

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.

best_match(\@supported, $header)

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.

Example:

print best_match(['application/xbel+xml', 'text/xml'],
    'text/*;q=0.5,*/*; q=0.1');
# text/xml

get_body($cgi)

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.

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.

fitness_and_quality_parsed($mime_type, @parsed_ranges)

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.

media_type($cgi, \@types)

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.

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 an empty string.

parse_media_range($range)

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.

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.

parse_mime_type($mime_type)

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 })

quality($mime_type, $ranges)

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

quality_parsed($mime_type, @parsed_ranges)

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.

request_method($cgi)

This function returns the query's HTTP request method.

Example 1:

my $method = request_method($cgi);

This function takes a CGI or compatible object as its first parameter.

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:

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.

THANKS

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/)

AUTHOR

Jaldhar H. Vyas, <jaldhar at braincells.com>

LICENSE AND COPYRIGHT

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.