CloudApp::REST - Perl Interface to the CloudApp REST API
Version 0.02
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;
Creates and returns a new instance.
Note: username is now an alias for the email method, provided for legacy!
username
email
Parameters:
$email
Sets the email address for requests that need authentication. Unless you only use "get_item" an email address is required.
$password
Sets the password for requests that need authentication. Unless you only use "get_item" a password is required.
\%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.
CloudApp::REST::Item::*
uri
slug
The URI to the CloudApp item, eg. http://cl.ly/abc123.
http://cl.ly/abc123
Basically this can be an arbitraty URI pointing anywhere, as long as the app behind it supports the CloudApp API.
The so called slug of an CloudApp Item, eg. abc123 for the item at http://cl.ly/abc123.
abc123
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.
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.
per_page
limit
If not present, defaults to 5.
5
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!
page
2
6
If page and offset are not present, page defaults to 1.
offset
1
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.
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.
type
archive
CloudApp::REST::Item::Archive
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.
false
Accepts the same parameters as "get_items", except for deleted. "get_trash" is nly a small wrapper around "get_items".
deleted
Creates a bookmark at CloudApp and returns the newly created bookmark as a CloudApp::REST::Item::Bookmark object.
Required.
The name of the bookmark, eg. 12. Deutscher Perl Workshop.
12. Deutscher Perl Workshop
The URI of the bookmark, eg. http://conferences.yapceurope.org/gpw2010/.
http://conferences.yapceurope.org/gpw2010/
Uploads a local file to CloudApp and returns the corresponding CloudApp::REST::Item::* object.
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.
$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.
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 to authenticate with. Use one of them to access "email".
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.
Registers an CloudApp account using the given email and password and returns the data returned by the API call as hash ref.
Email address (username) to register.
Password for the user.
You can control some behaviour by setting different flags or change some attributes or settings. Use them as methods.
$bool
Activates the debug mode by passing a true value. Defaults to 0. Debug messages are printed with warn.
0
warn
$new_name
Redefines the name of the user agent, defaults to module name and version.
$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!
http://my.cl.ly/
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!
http://cl.ly/
$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!
netloc
my.cl.ly:80
$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!
realm
Application
$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.
http
\%item
Expects an hashref of an item and returns the appropriate CloudApp::REST::Item::* module.
\@items
Expects an arrayref of items and returns a list of appropriate CloudApp::REST::Item::* objects as arrayref or array, depending on your context.
Executes each request and communicates with the CloudApp API.
The URI that is requested, eg. http://my.cl.ly/items?page=1&per_page=5.
http://my.cl.ly/items?page=1&per_page=5
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
method
POST
GET
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).
file
If noredirect is set to a true value, this method won't follow any redirects.
noredirect
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.
successful
2xx
302
303
@msgs
Small debug message handler that warns @msgs joined with a line break. Only prints if debug set to true.
debug
true
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.
bug-cloudapp-api at rt.cpan.org
Thanks to linebreak http://www.bylinebreak.com/ for making such a cool application, CloudApp. Go get yourself an account at http://www.getcloudapp.com/!
CloudApp::REST::Item
CloudApp::REST::Item::Audio
CloudApp::REST::Item::Bookmark
CloudApp::REST::Item::Image
CloudApp::REST::Item::Pdf
CloudApp::REST::Item::Text
CloudApp::REST::Item::Unknown
CloudApp::REST::Item::Video
Matthias Dietrich, <perl@rainboxx.de>
<perl@rainboxx.de>
http://www.rainboxx.de
Copyright 2010 Matthias Dietrich.
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.