NAME

REST::Utils - Utility functions for REST applications

SYNOPSIS

    use REST::Utils qw( :all );

VERSION

This document describes REST::Utils Version 0.3

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

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

  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/

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.

cpanm REST::Utils

perl -MCPAN -e shell
install REST::Utils