NAME

WebService::XING - Perl Interface to the XING API

VERSION

Version 0.001

SYNOPSIS

  use WebService::XING;

  my $xing = WebService::XING->new(
    key => $CUSTOMER_KEY,
    secret => $CUSTOMER_SECRET,
    access_token => $access_token,
    access_secret => $access_secret,
    user_id => $user_id,
  );

  $res = $xing->get_user_details(id => 'me')
    or die $res;

  say "Hello, I'm ", $res->content->{users}->[0]->{display_name};

DESCRIPTION

WebService::XING is a Perl client library for the XING API. It supports the whole range of functions described under https://dev.xing.com/.

Method Introspection

An application can query a list of all available API functions together with their parameters. See the "functions" function and the "function" and "can" method for more information.

Alpha Software Warning

This software is still very young and should not be considered stable. You are welcome to check it out, but be prepared: it might kill your kittens!

Moreover at the time of writing, the XING API is in a closed beta test phase, and still has a couple of bugs.

ATTRIBUTES

All attributes can be set in the constructor.

Attributes marked as "required and read-only" must be given in the constructor.

All writeable attributes can be used as setters and getters of the object instance.

All writeable attributes return the object in set mode to make them chainable. This example does virtually the same as in the "SYNOPSIS" above:

  $res = WebService::XING->new(
    key => $CUSTOMER_KEY,
    secret => $CUSTOMER_SECRET
  )
    ->access_token($token)
    ->access_secret($secret)
    ->user_id($uid)
    ->get_user_details(id => 'me')
      or die $res;

  say "Hello, I'm ", $res->content->{users}->[0]->{display_name};

All attributes with a default value are "lazy": They get their value when they are read the first time, unless they are already initialized. To get the default value, an attribute calls a builder method called "_build_" . $attribute_name. This gives a sub class of WebService::XING the opportunity to override any default value by providing a custom builder method.

key

The application key a.k.a. "consumer key". Required and read-only.

secret

The application secret a.k.a. "consumer secret". Required and read-only.

access_token

  $xing = $xing->access_token($access_token);
  $access_token = $xing->access_token;

Access token as returned at the end of the OAuth process. Required for all methods except "login" and "auth".

access_secret

  $xing = $xing->access_secret($access_secret);
  $access_secret = $xing->access_secret;

Access secret as returned at the end of the OAuth process. Required for all methods except "login" and "auth".

user_id

  $xing = $xing->user_id($user_id);
  $user_id = $xing->user_id;

The scrambled XING user id as returned (and set) by the "auth" method.

access_credentials

  $xing = $xing->access_credentials(
    $access_token, $access_secret, $user_id
  );
  ($access_token, $access_secret, $user_id) =
    $xing->access_credentials;

Convenience access attribute accessor, for getting and setting "access_token", "access_secret" and "user_id" in one go.

Once authorization has completed, "access_token", "access_secret" and "user_id" are the only variable attributes, that are needed to use all API functions. An application must store these three values for later authentication, a web application might put them in a long lasting session.

user_agent

  $xing = $xing->user_agent('MyApp Agent/23');
  $user_agent = $xing->user_agent;

Set or get the user agent string for the request.

Default: WebService::XING/$VERSION (Perl)

request_timeout

  $xing = $xing->request_timeout(10);
  $request_timeout = $xing->request_timeout;

Maximum time in seconds to wait for a response.

Default: 30

json

  $xing = $xing->json(My::JSON->new);
  $json = $xinf->json;

An object instance of a JSON class.

Default: JSON->new->utf8->allow_nonref. Uses JSON::XS if available.

warn

  $xing = $xing->warn(sub { $log->write(@_) });
  $xing->warn->($warning);

A reference to a sub, that handles warnings.

Default: sub { Carp::carp @_ } Used by the library to issue warnings.

die

  $xing = $xing->die(sub { MyException->throw(@_ });
  $xing->die->($famous_last_words);

A reference to a sub, that handles dies. Used by the library for dying.

Default: sub { Carp::croak @_ }

base_url

  $xing = $xing->base_url($test_url);
  $base_url = $xing->base_url;

Web address of the XING API server. Do not change unless you know what you are doing.

Default: https://api.xing.com

request_token_resource

  $xing = $xing->request_token_resource($request_token_resource);
  $request_token_resource = $xing->request_token_resource;

Resource where to receive an OAuth request token. Do not change without reason.

Default: /v1/request_token

authorize_resource

  $xing = $xing->authorize_resource($authorize_resource);
  $authorize_resource = $xing->authorize_resource;

Resource where the user has to be redirected in order to authorize access for the consumer. Do not change without reason.

Default: /v1/authorize

access_token_resource

  $xing = $xing->access_token_resource($access_token_resource);
  $access_token_resource = $xing->access_token_resource;

Resource where to receive an OAuth access token. Do not change without reason.

Default: /v1/access_token

FUNCTIONS

None of the functions is exported.

All functions can also be called as (either class or object) methods.

functions

  $functions = WebService::XING::functions;
  $functions = WebService::XING->functions;
  $functions = $xing->functions;

A function, that provides a reference to a list of the names of all the API's functions. The order is the same as documented under https://dev.xing.com/docs/resources.

function

  $function = WebService::XING::function($name);
  $function = WebService::XING->function($name);
  $function = $xing->function($name);

Get a WebService::XING::Function object for the given function $name. Return undef if no function with the given $name is known.

nonce

  $nonce = WebService::XING::nonce;
  $nonce = WebService::XING::nonce($any, $kind, $of, @input);

A function that creates a random string. While this is used internally, it is documented here, so you can use it if you like. Accepts any number of arbitrary volatile arguments to increase entropy. Works as a method too, with the nice side effect, that the object serves as entropy argument:

  $nonce = $xing->nonce;

METHODS

All methods are called with named arguments - or in other words - with a list of key-value-pairs.

All methods except "new" and "function" return a WebService::XING::Response object on success.

All methods except "new", "function", "login" and "auth" return a WebService::XING::Error object (which is actually a child class of WebService::XING::Response) on failure. A method may "die" if called inaccurately (e.g. with missing arguments).

When the method documentation mentions a $bool argument, it means boolean in the way Perl handles it: undef, "" and 0 being false and everything else true.

new

  my $xing = WebService::XING->new(
    key => $CUSTOMER_KEY,
    secret => $CUSTOMER_SECRET,
    access_token => $access_token,
    access_secret => $access_secret,
  );

The object constructor requires "key" and "secret" to be set, and for all methods besides "login" and "auth" also "access_token" and "access_secret". Any other attribute can be set here as well.

can

  $code = $xing->can($name);

Overrides "can" in UNIVERSAL. Usually API functions are dynamically built at first time they are called. can does the same, but rather than executing the method, it just returns a reference to it.

  $res = $xing->login or die $res;
  my $c = $res->content;
  my ($auth_url, $token, $secret) = @c{qw(url token token_secret)};

  $res = $xing->login(callback => $callback_url) or die $res;
  ...

OAuth handshake step 1: Obtain a request token.

If a callback url is given, the user will be re-directed back to that location from the XING authorization page after successfull completion of OAuth handshake step 2, otherwise (or if callback has the value oob) a PIN code (oauth_verifier) is displayed to the user on the XING authorization page, that must be entered in the consuming application.

An undef value is returned to indicate an error, the "error" attribute contains a WebServive::XING::Error object for further investigation.

The content property of the response contains a hash with the following elements:

url:: The XING authorization URL. For the second step of the OAuth handshake the user must be redirected to that location.
token:: The request token. Needed in "auth".
token_secret:: The request token secret. Needed in "auth".

auth

  $xing->auth(
    token => $token,
    token_secret => $token_secret,
    verifier => $verifier,
  );

OAuth handshake step 3: Obtain an access token. Requires a list of the following three named parameters:

token:: The request token as returned in the response of a successfull login call.
token_secret:: The request token_secret as returned in the response of a successfull login call.
verifier:: The OAuth verifier, that is provided to the callback as the oauth_verifier parameter - or that is displayed to the user for an out-of-band authorization.

The content property of the response contains a hash with the following elements:

token:: The access token.
token_secret:: The access token secret.
user_id:: The scrambled XING user id.

These three values are also stored in the object instance, so it is not strictly required to store them. It might be useful for a web application though, to keep only these access credentials in a session, rather than the whole WebService::XING object.

get_user_details

  $res = $xing->get_user_details(id => $id, fields => \@fields);

See https://dev.xing.com/docs/get/users/:id

create_status_message

  $res = $xing->create_status_message(id => $id, message => $message);

See https://dev.xing.com/docs/post/users/:id/status_message

get_profile_message

  $res = $xing->get_profile_message(user_id => $id);

See https://dev.xing.com/docs/get/users/:user_id/profile_message

update_profile_message

  $res = $xing->update_profile_message(
    user_id => $id, message => $message, public => $bool
  );

See https://dev.xing.com/docs/put/users/:user_id/profile_message

get_contacts

  $res = $xing->get_contacts(
    user_id => $id,
    limit => $limit, offset => $offset, order_by => $order_by,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:user_id/contacts

get_shared_contacts

  $res = $xing->get_shared_contacts(
    user_id => $id,
    limit => $limit, offset => $offset, order_by => $order_by,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:user_id/contacts/shared

get_incoming_contact_requests

  $res = $xing->get_incoming_contact_requests(
    user_id => $id,
    limit => $limit, offset => $offset,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:user_id/contact_requests

get_sent_contact_requests

  $res = $xing->get_sent_contact_requests(
    user_id => $id, limit => $limit, offset => $offset
  );

See https://dev.xing.com/docs/get/users/:user_id/contact_requests/sent

create_contact_request

  $res = $xing->create_contact_request(
    user_id => $id, message => $message
  );

See https://dev.xing.com/docs/post/users/:user_id/contact_requests

accept_contact_request

  $res = $xing->accept_contact_request(
    id => $sender_id, user_id => $recipient_id
  );

See https://dev.xing.com/docs/put/users/:user_id/contact_requests/:id/accept

delete_contact_request

  $res = $xing->delete_contact_request(
    id => $sender_id, user_id => $recipient_id
  );

See https://dev.xing.com/docs/delete/users/:user_id/contact_requests/:id

get_contact_paths

  $res = $xing->get_contact_paths(
    user_id => $id,
    other_user_id => $other_user_id,
    all_paths => $bool,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:user_id/network/:other_user_id/paths

get_bookmarks

  $res = $xing->get_bookmarks(
    user_id => $id,
    limit => $limit, offset => $offset,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:user_id/bookmarks

create_bookmark

  $res = $xing->create_bookmark(id => $id, user_id => $id);

See https://dev.xing.com/docs/put/users/:user_id/bookmarks/:id

delete_bookmark

  $res = $xing->delete_bookmark(id => $id, user_id => $id);

See https://dev.xing.com/docs/delete/users/:user_id/bookmarks/:id

get_network_feed

  $res = $xing->get_network_feed(
    user_id => $id,
    aggregate => $bool,
    since => $date,
    user_fields => \@user_fields
  );

  $res = $xing->get_network_feed(
    user_id => $id,
    aggregate => $bool,
    until => $date,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:user_id/network_feed

get_user_feed

  $res = $xing->get_user_feed(
    user_id => $id,
    since => $date,
    user_fields => \@user_fields
  );

  $res = $xing->get_user_feed(
    user_id => $id,
    until => $date,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:id/feed

get_activity

  $res = $xing->get_activity(id => $id, user_fields => \@user_fields);

See https://dev.xing.com/docs/get/activities/:id

share_activity

  $res = $xing->share_activity(id => $id, text => $text);

See https://dev.xing.com/docs/post/activities/:id/share

delete_activity

  $res = $xing->delete_activity(id => $id);

See https://dev.xing.com/docs/delete/activities/:id

get_activity_comments

  $res = $xing->get_activity_comments(
    activity_id => $activity_id,
    limit => $limit, offset => $offset,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/activities/:activity_id/comments

create_activity_comment

  $res = $xing->create_activity_comment(
    activity_id => $activity_id,
    text => $text
  );

See https://dev.xing.com/docs/post/activities/:activity_id/comments

delete_activity_comment

  $res = $xing->delete_activity_comment(
    activity_id => $activity_id,
    id => $id
  );

See https://dev.xing.com/docs/delete/activities/:activity_id/comments/:id

get_activity_likes

  $res = $xing->get_activity_likes(
    activity_id => $activity_id,
    limit => $limit, offset => $offset,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/activities/:activity_id/likes

create_activity_like

  $res = $xing->create_activity_like(activity_id => $activity_id);

See https://dev.xing.com/docs/put/activities/:activity_id/like

delete_activity_like

  $res = $xing->delete_activity_like(activity_id => $activity_id);

See https://dev.xing.com/docs/delete/activities/:activity_id/like

get_profile_visits

  $res = $xing->create_profile_visit(
    user_id => $id,
    limit => $limit, offset => $offset,
    since => $date,
    strip_html => $bool
  );

See https://dev.xing.com/docs/get/users/:user_id/visits

create_profile_visit

  $res = $xing->get_profile_visits(user_id => $id);

See https://dev.xing.com/docs/post/users/:user_id/visits

get_recommendations

  $res = $xing->get_recommendations(
    user_id => $id,
    limit => $limit, offset => $offset,
    similar_user_id => $similar_user_id,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:user_id/network/recommendations

create_invitations

  $res = $xing->create_invitations(
    to_emails => \@to_emails,
    message => $message,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/post/users/invite

update_geo_location

  $res = $xing->update_geo_location(
    user_id => $id,
    accuracy => $accuracy,
    latitude => $latitude, longitude => $longitude,
    ttl => $ttl
  );

See https://dev.xing.com/docs/put/users/:user_id/geo_location

get_nearby_users

  $res = $xing->get_nearby_users(
    user_id => $id,
    age => $age,
    radius => $radius,
    user_fields => \@user_fields
  );

See https://dev.xing.com/docs/get/users/:user_id/nearby_users

request

  $res = $xing->request($method => $resource, @args);

Call any API function:

$method:: GET, POST, PUT or DELETE.
$resource:: An api resource, e.g. /v1/users/me.
@args:: A list of named arguments, e.g. id => 'me', text => 'Blah!'.

AUTHOR

Bernhard Graf, <graf (a) cpan.org>

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 WebService::XING, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WebService::XING

CPAN shell

perl -MCPAN -e shell
install WebService::XING

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)