NAME

WebService::XING - Perl Interface to the XING API

VERSION

Version 0.020

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, my name is ", $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" and the "function" function, and the "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, my name is ", $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. The attribute default value is set by 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 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 a temporary 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. Returns undef if no function with the given $name is known.

nonce

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

A function, that creates a random string. While intended primarily for internal use, it is documented here, so you can use it if you like. Accepts any number of arbitrary volatile arguments to increase entropy.

METHODS

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

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

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.

login

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

or

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

OAuth handshake step 1: Obtain a temporary 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.

Always returns a WebServive::XING::Response object.

"content" in WebService::XING::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 temporary request token. Needed in "auth".

token_secret:

The temporary 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 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

find_user_by_email_address

$res = $xing->find_by_emails(
  emails => \@emails, user_fields => \@user_fields
);

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

list_conversations

$res = $xing->list_conversations(
  user_id => $user_id, limit => $limit, offset => $offset,
  user_fields => \@user_fields, with_latest_messages => $number
);

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

get_conversation

$res = $xing->get_conversation(
  user_id => $user_id, id => $conversation_id,
  user_fields => \@user_fields, with_latest_messages => $number
);

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

list_conversation_messages

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

See https://dev.xing.com/docs/get/users/:user_id/conversations/:conversation_id/messages

get_conversation_message

$res = $xing->get_conversation_message(
  user_id => $user_id, conversation_id => $conversation_id,
  id => $message_id, user_fields => \@user_fields
);

See https://dev.xing.com/docs/get/users/:user_id/conversations/:conversation_id/messages/: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 => $user_id);

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

update_profile_message

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

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

list_contacts

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

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

list_shared_contacts

$res = $xing->list_shared_contacts(
  user_id => $user_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

list_incoming_contact_requests

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

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

list_sent_contact_requests

$res = $xing->list_sent_contact_requests(
  user_id => $user_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 => $user_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 => $user_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

list_bookmarks

$res = $xing->list_bookmarks(
  user_id => $user_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 => $user_id);

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

delete_bookmark

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

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

get_network_feed

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

$res = $xing->get_network_feed(
  user_id => $user_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 => $user_id,
  since => $date,
  user_fields => \@user_fields
);

$res = $xing->get_user_feed(
  user_id => $user_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

list_activity_comments

$res = $xing->list_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

list_activity_likes

$res = $xing->list_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

list_profile_visits

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

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

create_profile_visit

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

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

list_recommendations

$res = $xing->list_recommendations(
  user_id => $user_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

delete_recommendation

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

See https://dev.xing.com/docs/delete/users/:user_id/network/recommendations/user/:id

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 => $user_id,
  accuracy => $accuracy,
  latitude => $latitude, longitude => $longitude,
  ttl => $ttl
);

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

list_nearby_users

$res = $xing->list_nearby_users(
  user_id => $user_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!'.

DEPRECATED METHODS

For the sake of consistency a couple of API methods have been renamed. These methods are still available under their old names. The old names are not detectable by means of "Method Introspection", and will be removed in a future release.

get_contacts

Renamed to "list_contacts".

get_shared_contacts

Renamed to "list_shared_contacts".

get_incoming_contact_requests

Renamed to "list_incoming_contact_requests".

get_sent_contact_requests

Renamed to "list_sent_contact_requests".

get_bookmarks

Renamed to "list_bookmarks".

get_activity_comments

Renamed to "list_activity_comments".

get_activity_likes

Renamed to "list_activity_likes".

get_profile_visits

Renamed to "list_profile_visits".

get_recommendations

Renamed to "list_recommendations".

block_recommendation

Renamed to "delete_recommendation".

get_nearby_users

Renamed to "list_nearby_users".

SEE ALSO

WebService::XING::Response, WebService::XING::Function, https://dev.xing.com/

AUTHOR

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

LICENSE AND COPYRIGHT

Copyright 2012 Bernhard Graf.

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.

cpanm WebService::XING

perl -MCPAN -e shell
install WebService::XING