/ 
WWW-Formspring-0.03
River stage zero No dependents
/ WWW::Formspring

NAME

WWW::Formspring - Perl interface for formspring.me

SYNOPSIS

use WWW::Formspring;
my $fs = WWW::Formspring->new({
                       access_token => "xxx",
                       access_secret => "yyy",
                       consumer_secret => "aaa",
                       consumer_key => "bbb",
                       username => "johndoe",
                   });

$fs->profile_ask("worr2400", "Hey, what's up?");

DESCRIPTION

This is a Perl interface for the very beta formspring.me API. This module is subject to breakage as they play with the final spec of their API. Most methods share names with the paths of the API counterparts, making the formspring API documentation on dev.formspring.me just as useful as this documentation.

EXPORT

None by default.

ATTRIBUTES

The constructor can take any of these attributes in a hashref, just like normal Moose objects. Read-only attributes that are not for use outside of the module are not described here, and it is not recommended that you change their values on construction.

username

Supply a default username. Any method that takes a username may use this username if none is provided. Also used when posting questions non-anonymously.

consumer_key

OAuth consumer key for authentication.

consumer_secret

OAuth consumer secret for authentication. Be sure to keep this safe somewhere.

access_token

OAuth access token for a user after they have successfully authorized your app to access their account.

access_secret

OAuth access token secret for a user after they have successfully authorized your app to access their account. Like the consumer secret, you should try and keep this safe somewhere.

callback_url

URL for OAuth to redirect to in after authorization has occurred. Defaults to 'oob' for desktop apps, which means that no redirection occurs, and that they are provided a pin to manually enter into your application.

OAUTH AUTHENTICATION

WWW::Formspring uses Net::OAuth to handle authentication. It abstracts away some of the messy details, of using formspring's OAuth from the programmer.

To outline the process, first you need to get a request token, then redirect the user to the Formspring authorization page. Your app will either get a PIN from the user, or a get a PIN as a parameter to your callback_url. Then, with the request token info and the PIN, you can get access tokens which will allow your app to authenticate as the user again and again. So it would be a good idea to store these somewhere persistent.

Getting a request token

NOTE: consumer_key and consumer_secret must be set for this function call to work.

my $request_token = $fs->get_request_token

Redirecting the user

Redirect the user to formspring authorization page:

my $auth_url = $fs->auth_url."?token=".$request_token->{token}."&secret="$request_token->{token_secret}

Getting the access token

Depending on the value of callback_url, you will either have to prompt the user for a PIN, or get the pin as a parameter to your callback_url. Pass this in with the request token and secret to get_access_token, and you'll get your access token and secret.

$fs->get_access_token($request_token->{token}, $request_token->{token_secret}, $pin)

METHODS

get_request_token

Gets a request token from formspring.me as the first step of OAuth authentication. Returns a hashref with keys token and token_secret. consumer_key, consumer_secret, and callback_url must be set before you call this method.

get_access_token($request_token, $request_token_secret, $verifier)

Gets an access token from formspring.me as the last step of OAuth verification. Takes the token and secret from get_request_token, as well as the oauth_verifier that was received as a parameter to your callback URL, or as a PIN from the formspring site.

answered_count
answered_count($username)

Gets the answer count, as an int, of the provided (or default) username.

answered_details($id)
answered_details($response)
answered_details($id, $username)

Gets the all of the information you could ever want about a specific question of the id and username provided. Returns a filled out WWW::Formspring::Response object.

Can also fill out a user created WWW::Formspring::Response object if at least the asked_to and the id are present.

answered_list
answered_list($user)
answered_list($username)
answered_list($username, $max_id)
answered_list($username, $max_id, $since_id)

Gets a list of questions and answers from given (or default) username. Returns an arrayref of WWW::Formspring::Response objects. If max_id parameter is provided, it will get all responses from before the given id. Can also take a WWW::Formspring::User object. If since_id is also set, it will get only posts after the id passed.

answered_remove($id)
answered_remove($question)

Deletes an answered question from the authenticated user by id and returns it to the inbox. Takes either a numeric question id or a WWW::Formspring::Response object. Returns 0 on success.

follow_add($user)
follow_add($username)

Adds the provided user to the authenticated users followed list. Takes either a string or a WWW::Formspring::User object. Returns a 0 on success.

follow_answers
follow_answers($max_id)
follow_answers($max_id, $since_id)

Gets all of the questions and answers from the authenticated user's friends. Returns an arrayref of WWW::Formspring::Response objects. If $max_id is provided, then it only fetches questions from before the passed in id. If $since_id is also passed in, it will get only posts after the post of the id specified.

follow_count

Returns the number of people the authenticated user is following.

follow_list
follow_list($page)

Get list of people the authenticated use is following. If page is provided, get that page of results (100 per page). Else, returns the first page. Returns an arrayref of WWW::Formspring::User objects.

follow_remove($username)

Removes the passed in user from the authenticated user's follower list. Returns 0 on success.

inbox_block($question)
inbox_block($id)
inbox_block($id, $reason)

Deletes a question from the authenticated user's inbox and blocks the user from asking anymore questions to the authenticated user. A numeric id can be provided as well as a WWW::Formspring::Response. $reason can be either "spam" or "abuse," but does not need to be provided at all. Returns 0 on success.

inbox_count

Returns the number of questions in the authenticated user's inbox.

inbox_list
inbox_list($max_id)
inbox_list($max_id, $since_id)

Returns a list of questions in the authenticated user's inbox. If $max_id is provided, then no questions later than $max_id will be returned. If $since_id is provided, no questions before $since_id will be returned. Either value can be 0 to indicate that you do not wish to use that parameter.

Returns an arrayref of WWW::Formspring::Response objects.

inbox_random

Asks the authenticated user a random questions generated by the site. Returns a WWW::Formspring object.

inbox_remove($question)
inbox_remove($id)

Removes a question from the authenticated user's inbox. Takes either a numeric id or a WWW::Formspring::Response object. Returns 0 on success.

inbox_respond($question)
inbox_respond($id, $response)

Respond to a question in the authenticated user's inbox. $question must be a WWW::Formspring::Question object, however you can also just provide the id of the question and the user's response. Returns 0 on success.

profile_ask($question)
profile_ask($username, $question, $anonymous)

Ask a question to a user. $question must be a WWW::Formspring::Response object. In this case, anonymity is determined by whether or not the WWW::Formspring::Response object contains a valid WWW::Formspring::User object in the asked_by field. The user that the question is directed at goes in the asked_to field as a WWW::Formspring::User object.

Alternatively, strings can be provided in the place of objects. $anonymous can be 1 or 0 to represent true or false.

profile_details
profile_details($user)
profile_details($username)

Get user details based on passed in username. If no username is provided, then the default username IS NOT used, and the details on the authenticated user is provided instead (as directed by the formspring API). Returns a WWW::Formspring::User object.

search_profiles($query)
search_profiles($query, $page)

Searches profiles based on $query. If $page is provided, that page is returned. Returns page 1 by default, 50 results per page. A max of 20 pages will be returned by the search function.

WWW::Formspring::User

This object represents a formspring.me user, and it has the following accessors/mutators

username
name
website
location
bio
photo_url
answered_count
is_following

WWW::Formspring::Question

This represents a formspring.me question, and has the following accessors/mutators

id
question
time
asked_by
asked_to
ask

This asks the user in the ask_to field the question. You can fill out a Question object and just call ask on it and it will submit the question.

WWW::Formspring::Response

This represents a response to a question, and inherits from WWW::Formspring::Question. Additionally it includes the following

answer
respond

Like the Question object, you can fill out a response object that references a formspring question and a response and then call respond on it to respond to it.

SEE ALSO

Mention other useful documentation such as the documentation of related modules or operating system documentation (such as man pages in UNIX), or any relevant external documentation such as RFCs or standards.

If you have a mailing list set up for your module, mention it here.

If you have a web site set up for your module, mention it here.

AUTHOR

William Orr, <will@worrbase.com>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by William Orr

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.