/ 
OAuthomatic-0.0202
River stage zero No dependents
/ OAuthomatic::Caller

NAME

OAuthomatic::Caller - actually make OAuth-signed calls

VERSION

version 0.0202

DESCRIPTION

Sign OAuth calls and execute them.

This object is mostly used internally by OAuthomatic, but may be useful separately if you want to implement initialization scheme by yourself but prefer it's API and structural exceptions to raw Net::OAuth.

METHODS

create_authorization_url($callback_url) => TemporaryCred

Calculates URL which user should visit to authorize app (and associated temporary token).

create_token_cred

Acquires access token, preserves them in the object (so future calls will be authenticated), and return (so it can be saved etc).

build_oauth_request(method => ..., ...)

Prepare properly signed HTTP::Request but do not execute it, just return ready-to-be-sent object.

Parameters: identical as in "execute_oauth_request"

execute_oauth_request(method => $method, url => $url, url_args => $args, body_form => $body_form, body => $body, content_type => $content_type)

Make a request to url using the given HTTP method and signing request with OAuth credentials.

method

One of GET, POST, PUT, DELETE.

url

Actual URL to call (http://some.site.com/api/...)

url_args (optional)

Additional arguments to escape and add to the URL. This is simply shortcut, three calls below are equivalent:

$c->execute_oauth_request(method => "GET",
    url => "http://some.where/api?x=1&y=2&z=a+b");

$c->execute_oauth_request(method => "GET",
    url => "http://some.where/api",
    url_args => {x => 1, y => 2, z => 'a b'});

$c->execute_oauth_request(method => "GET",
    url => "http://some.where/api?x=1",
    url_args => {y => 2, z => 'a b'});
body_form OR body

Exactly one of those must be specified for POST and PUT (none for GET or DELETE).

Specifying body_form means, that we are creating www-urlencoded form. Parameters will be included in OAuth signature. Example:

$c->execute_oauth_request(method => "POST",
    url => "http://some.where/api",
    body_form => {par1 => 'abc', par2 => 'd f'});

Note that this is not just a shortcut for setting body to already serialized form. Case of urlencoded form is treated in a special way by OAuth (those values impact OAuth signature). To avoid signature verification errors, OAuthomatic will reject such attempts:

# WRONG AND WILL FAIL. Use body_form if you post form.
$c->execute_oauth_request(method => "POST",
    url => "http://some.where/api",
    body => 'par1=abc&par2=d+f',
    content_type => 'application/x-www-form-urlencoded');

Specifying body means, that we post non-form body (for example JSON, XML or even binary data). Example:

$c->execute_oauth_request(method => "POST",
    url => "http://some.where/api",
    body => "<product><item-no>3434</item-no><price>334.22</price></product>",
    content_type => "application/xml; charset=utf-8");

Value of body can be either binary string (which will be posted as-is), or perl unicode string (which will be encoded according to the content type, what by default means utf-8).

Such content is not covered by OAuth signature, so less secure (at least if it is posted over non-SSL connection).

For longer bodies, references are supported:

$c->execute_oauth_request(method => "POST",
    url => "http://some.where/api",
    body => \$body_string,
    content_type => "application/xml; charset=utf-8");
content_type

Used to set content type of the request. If missing, it is set to text/plain; charset=utf-8 if body param is specified and to application/x-www-form-urlencoded; charset=utf-8 if body_form param is specified.

Note that module author does not test behaviour on encodings different than utf-8 (although they may work).

_execute_oauth_request_ext

Common code for API and OAuth-protocol calls. Uses all parameters described in "execute_oauth_request" and two additional:

class

ProtectedResource, UserAuth, RequestToken etc (XXX from Net::Oauth::XXXXRequest)

token

Actual token to use while signing (skip to use only client token) - either $self->token_cred, or some temporary_cred, depending on task at hand.

ATTRIBUTES

config

OAuthomatic::Config object used to bundle various configuration params.

server

OAuthomatic::Server object used to bundle server-related configuration params.

INTERNAL METHODS

_build_oauth_request_ext

Common code for API and OAuth-protocol calls. Uses all parameters described in "execute_oauth_request" and some additional:

class

ProtectedResource, UserAuth, RequestToken etc (XXX from Net::Oauth::XXXXRequest)

token

Actual token to use while signing (skip to use only client token) - either $self->token_cred, or some temporary_cred, depending on task at hand.

verifier

Verifier to be added to access token creation.

callback

Callback url for temporary token creation.

auth_in_post

True if authorization tokens are to be merged into POST body, false if they are to be preserved in Authorize header.

AUTHOR

Marcin Kasperski <Marcin.Kasperski@mekk.waw.pl>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Marcin Kasperski.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.