WebService::XING - Perl Interface to the XING API
Version 0.020
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};
WebService::XING is a Perl client library for the XING API. It supports the whole range of functions described under https://dev.xing.com/.
WebService::XING
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.
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.
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.
"_build_" . $attribute_name
The application key a.k.a. "consumer key". Required and read-only.
The application secret a.k.a. "consumer secret". Required and read-only.
$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".
$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".
$xing = $xing->user_id($user_id); $user_id = $xing->user_id;
The scrambled XING user id as returned (and set) by the "auth" method.
$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.
$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)
WebService::XING/$VERSION (Perl)
$xing = $xing->request_timeout(10); $request_timeout = $xing->request_timeout;
Maximum time in seconds to wait for a response.
Default: 30
30
$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.
JSON->new->utf8->allow_nonref
$xing = $xing->warn(sub { $log->write(@_) }); $xing->warn->($warning);
A reference to a sub, that handles warnings.
sub
warn
Default: sub { Carp::carp @_ } Used by the library to issue warnings.
sub { Carp::carp @_ }
$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.
die
Default: sub { Carp::croak @_ }
sub { Carp::croak @_ }
$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
https://api.xing.com
$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
$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
$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
None of the functions is exported.
All functions can also be called as (either class or object) methods.
$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 = 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.
$name
undef
$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.
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.
$bool
0
false
true
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.
$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.
can
$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.
oob
oauth_verifier
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".
$xing->auth( token => $token, token_secret => $token_secret, verifier => $verifier, );
OAuth handshake step 3: Obtain an access token. Requires the following three named parameters:
The request token as returned in the response of a successfull login call.
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:
The access token.
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.
$res = $xing->get_user_details(id => $id, fields => \@fields);
See https://dev.xing.com/docs/get/users/:id
$res = $xing->find_by_emails( emails => \@emails, user_fields => \@user_fields );
See https://dev.xing.com/docs/get/users/find_by_emails
$res = $xing->get_job_posting( id => $id, user_fields => \@user_fields );
See https://dev.xing.com/docs/get/jobs/:id
$res = $xing->find_jobs( query => $query, limit => $limit, location => $location, offset => $offset, user_fields => \@user_fields );
See https://dev.xing.com/docs/get/jobs/find
$res = $xing->list_job_recommendations( user_id => $user_id, limit => $limit, offset => $offset, user_fields => \@user_fields );
See https://dev.xing.com/docs/get/users/:user_id/jobs/recommendations
$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
$res = $xing->create_conversation( user_id => $user_id, content => $content, subject => $subject, recipient_ids => \@recipient_ids );
See https://dev.xing.com/docs/post/users/:user_id/conversations
$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
$res = $xing->mark_conversation_read( user_id => $user_id, id => $id );
See https://dev.xing.com/docs/put/users/:user_id/conversations/:id/read
$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
$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
$res = $xing->mark_conversation_message_read( user_id => $user_id, conversation_id => $conversation_id, id => $message_id );
See https://dev.xing.com/docs/put/users/:user_id/conversations/:conversation_id/messages/:id/read
$res = $xing->mark_conversation_message_unread( user_id => $user_id, conversation_id => $conversation_id, id => $message_id );
See https://dev.xing.com/docs/delete/users/:user_id/conversations/:conversation_id/messages/:id/read
$res = $xing->create_conversation_message( user_id => $user_id, conversation_id => $conversation_id, content => $content );
$res = $xing->delete_conversation( user_id => $user_id, id => $conversation_id );
See https://dev.xing.com/docs/delete/users/:user_id/conversations/:id
$res = $xing->create_status_message(id => $id, message => $message);
See https://dev.xing.com/docs/post/users/:id/status_message
$res = $xing->get_profile_message(user_id => $user_id);
See https://dev.xing.com/docs/get/users/:user_id/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
$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
$res = $xing->list_contacts( user_id => $user_id, contact_id => $contact_id );
See https://dev.xing.com/docs/get/users/:user_id/contacts/:contact_id/tags
$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
$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
$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
$res = $xing->create_contact_request( user_id => $user_id, message => $message );
See https://dev.xing.com/docs/post/users/:user_id/contact_requests
$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
$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
$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
$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
$res = $xing->create_bookmark(id => $id, user_id => $user_id);
See https://dev.xing.com/docs/put/users/:user_id/bookmarks/:id
$res = $xing->delete_bookmark(id => $id, user_id => $user_id);
See https://dev.xing.com/docs/delete/users/:user_id/bookmarks/:id
$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
$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
$res = $xing->get_activity(id => $id, user_fields => \@user_fields);
See https://dev.xing.com/docs/get/activities/:id
$res = $xing->share_activity(id => $id, text => $text);
See https://dev.xing.com/docs/post/activities/:id/share
$res = $xing->delete_activity(id => $id);
See https://dev.xing.com/docs/delete/activities/:id
$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
$res = $xing->create_activity_comment( activity_id => $activity_id, text => $text );
See https://dev.xing.com/docs/post/activities/:activity_id/comments
$res = $xing->delete_activity_comment( activity_id => $activity_id, id => $id );
See https://dev.xing.com/docs/delete/activities/:activity_id/comments/:id
$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
$res = $xing->create_activity_like(activity_id => $activity_id);
See https://dev.xing.com/docs/put/activities/:activity_id/like
$res = $xing->delete_activity_like(activity_id => $activity_id);
See https://dev.xing.com/docs/delete/activities/:activity_id/like
$res = $xing->list_profile_visits(user_id => $user_id);
See https://dev.xing.com/docs/get/users/:user_id/visits
$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
$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
$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
$res = $xing->create_invitations( to_emails => \@to_emails, message => $message, user_fields => \@user_fields );
See https://dev.xing.com/docs/post/users/invite
$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
$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
$res = $xing->request($method => $resource, @args);
Call any API function:
$method
GET, POST, PUT or DELETE.
GET
POST
PUT
DELETE
$resource
An api resource, e.g. /v1/users/me.
@args
A list of named arguments, e.g. id => 'me', text => 'Blah!'.
id => 'me', text => 'Blah!'
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.
Renamed to "list_contacts".
Renamed to "list_shared_contacts".
Renamed to "list_incoming_contact_requests".
Renamed to "list_sent_contact_requests".
Renamed to "list_bookmarks".
Renamed to "list_activity_comments".
Renamed to "list_activity_likes".
Renamed to "list_profile_visits".
Renamed to "list_recommendations".
Renamed to "delete_recommendation".
Renamed to "list_nearby_users".
WebService::XING::Response, WebService::XING::Function, https://dev.xing.com/
Bernhard Graf, <graf (a) cpan.org>
<graf (a) cpan.org>
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.
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.