OAuthomatic::Caller

- NAME
- VERSION
- DESCRIPTION
- METHODS
  - create_authorization_url($callback_url) => TemporaryCred
  - create_token_cred
  - build_oauth_request(method => ..., ...)
  - _execute_oauth_request_ext
- ATTRIBUTES
  - config
  - server
- INTERNAL METHODS
  - _build_oauth_request_ext
- AUTHOR
- COPYRIGHT AND LICENSE

# NAME

OAuthomatic::Caller - actually make OAuth-signed calls

# VERSION

version 0.01

# 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.