NAME

CloudApp::REST - Perl Interface to the CloudApp REST API

VERSION

Version 0.02

SYNOPSIS

This is a Perl Interface to the CloudApp REST API. You can find more information about CloudApp at http://www.getcloudapp.com/.

Here's an example on how to retrieve the last 5 items:

use CloudApp::REST;

my $cl = CloudApp::REST->new;

$cl->email('email@example.com');
$cl->password('my_supersafe_secret');

my $items = $cl->get_items;

SUBROUTINES/METHODS

new

Creates and returns a new instance.

email

Note: username is now an alias for the email method, provided for legacy!

Parameters:

$email

Sets the email address for requests that need authentication. Unless you only use "get_item" an email address is required.

password

Parameters:

$password

Sets the password for requests that need authentication. Unless you only use "get_item" a password is required.

get_item

Parameters:

\%params

Gets a single item from CloudApp and returns the appropriate CloudApp::REST::Item::* module. Only one of the following parameters should be given. However, if uri is given, slug is ignored.

uri => $uri

The URI to the CloudApp item, eg. http://cl.ly/abc123.

Basically this can be an arbitraty URI pointing anywhere, as long as the app behind it supports the CloudApp API.

slug => $slug

The so called slug of an CloudApp Item, eg. abc123 for the item at http://cl.ly/abc123.

get_items

Parameters:

\%params

Gets some or all items from CloudApp, depending on the parameters you pass in. Returns an arrayref or array (depending on your context) of appropriate CloudApp::REST::Item::* objects.

per_page => $n

limit => $n

Sets the maximum count of items per page and/or the maximum items you want to retrieve. If per_page is given, limit is ignored.

If not present, defaults to 5.

page => $n

Sets the current page you want to retrieve items from.

Example: If per_page or limit is 5 and page is 2, you will retrieve a maximum of 5 items starting at number 6 (1-based). If there are no such items, an empty arrayref is returned. Note: this behavior fully depends on the behaviour of the API!

If page and offset are not present, page defaults to 1.

offset => $n

As an alternative to page you can define an offset. If page is not given but offset is, offset is divided by per_page and then converted to an integer. The result is then used as page.

type => $type

If you want to get only a specific type of items, set type to an appropriate value. The value should be the last part of the module name of the appropriate CloudApp::REST::Item::* class in lower case, eg. archive for CloudApp::REST::Item::Archive. If you set type to a value that is not an item type, an empty list will be returned by this method.

deleted => $bool

Set to a true value if you want only items from the trash. Defaults to false. You may want to use the shortcut "get_trash" instead.

get_trash

Parameters:

\%params

Accepts the same parameters as "get_items", except for deleted. "get_trash" is nly a small wrapper around "get_items".

create_bookmark

Parameters:

\%params

Creates a bookmark at CloudApp and returns the newly created bookmark as a CloudApp::REST::Item::Bookmark object.

name => $name

Required.

The name of the bookmark, eg. 12. Deutscher Perl Workshop.

uri => $uri

Required.

The URI of the bookmark, eg. http://conferences.yapceurope.org/gpw2010/.

create_file

Parameters:

\%params

Uploads a local file to CloudApp and returns the corresponding CloudApp::REST::Item::* object.

file => $path_to_file

Required.

The path to the file that will be uploaded. If the file is not accessible or does not exist, "create_file" dies before trying to upload.

delete_item

Parameters:

$item

Deletes an item at CloudApp. $item has to be an CloudApp::REST::Item::* object.

Usually this method is called via "delete" in CloudApp::REST::Item of a CloudApp::REST::Item::* module object.

authenticate

Parameters:

\%params

Instead of using "email" and "password" directly you can pass along both parameters to "authenticate" to set the user data.

If one of the following parameters are not given, "authenticate" tries to find them in "email" or "password". If either parameter cannot be found, "authenticate" dies.

email => $email =item username => $email (Legacy) =item user => $email (Legacy): Email to authenticate with. Use one of them to access "email".
password => $password =item pass => $password: Password to authenticate with. Use one of them to access "password".

Note: the credentails passed through "authenticate" are not saved within the instance data of CloudApp::REST. As result only one request is handled with authentication, all following will be processed without it. Note that some API calles require authentication and if this data is not present when calling such a method, that method will die.

account_register

Parameters:

\%params

Registers an CloudApp account using the given email and password and returns the data returned by the API call as hash ref.

email => $email: Email address (username) to register.
password => $password =item pass => $password: Password for the user.

FLAGS, ATTRIBUTES AND SETTINGS

You can control some behaviour by setting different flags or change some attributes or settings. Use them as methods.

debug

Parameters:

$bool

Activates the debug mode by passing a true value. Defaults to 0. Debug messages are printed with warn.

agent_name

Parameters:

$new_name

Redefines the name of the user agent, defaults to module name and version.

private_base_url

Parameters:

$url

The hostname and the scheme of the private area (when auth is needed). Defaults to http://my.cl.ly/. Usually there is no need to change this!

public_base_url

Parameters:

$url

The hostname and the scheme of the public area (when auth is not needed). Defaults to http://cl.ly/. Usually there is no need to change this!

auth_netloc

Parameters:

$netloc

The so called netloc for authentication, as LWP::UserAgent requires. Defaults to my.cl.ly:80. Usually there is no need to change this!

auth_realm

Parameters:

$real

The so-called realm for authentication, as required by LWP::UserAgent and the CloudApp API. Defaults to Application. Usually there is no need to change this!

proxy

Parameters:

$proxy_url

If you need to set a proxy, use this method. Pass in a proxy URL and port for an http proxy. If not set, no proxy is used.

INTERNAL METHODS

_build_item

Parameters:

\%item

Expects an hashref of an item and returns the appropriate CloudApp::REST::Item::* module.

_build_items

Parameters:

\@items

Expects an arrayref of items and returns a list of appropriate CloudApp::REST::Item::* objects as arrayref or array, depending on your context.

_get_response

Parameters:

\%params

Executes each request and communicates with the CloudApp API.

uri => $uri

The URI that is requested, eg. http://my.cl.ly/items?page=1&per_page=5.

method => $method

The HTTP method of the request type. If the parameter params to "_get_response" is set, method is ignored and set to POST, otherwise to the value of method. Defaults to GET in all other cases.

params => \%params

If params is set, the keys and values are used as POST parameters with their values, the HTTP method is set to POST.

If params has a key file, this method tries to upload that file. However, it is not checked if the file exists (you need to do this by yourself if you use this method directly).

noredirect => $bool

If noredirect is set to a true value, this method won't follow any redirects.

Some notes:

After each call, the current user agent instance is destroyed. This is done to reset the redirect status so that the next request won't contain auth data unless required.
This method handles all HTTP status codes that are considered as successful (all 2xx codes) and the codes 302 and 303. If other status codes are returned, the request is considered an error and the method dies.

_debug

Parameters:

@msgs

Small debug message handler that warns @msgs joined with a line break. Only prints if debug set to true.

BUGS

Please report any bugs or feature requests to bug-cloudapp-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CloudApp-REST. I will be notified, and then you'll automatically be updated on the progress of your report as I make changes.

ACKNOWLEDGEMENTS

Thanks to linebreak http://www.bylinebreak.com/ for making such a cool application, CloudApp. Go get yourself an account at http://www.getcloudapp.com/!

AUTHOR

Matthias Dietrich, <perl@rainboxx.de>

http://www.rainboxx.de

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install CloudApp::REST, copy and paste the appropriate command in to your terminal.

cpanm

cpanm CloudApp::REST

CPAN shell

perl -MCPAN -e shell
install CloudApp::REST

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

SUBROUTINES/METHODS

new

email

password

get_item

get_items

get_trash

create_bookmark

create_file

delete_item

authenticate

account_register

FLAGS, ATTRIBUTES AND SETTINGS

INTERNAL METHODS

_build_item

_build_items

_get_response

_debug

BUGS

ACKNOWLEDGEMENTS

SEE ALSO

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions