As you will already know, in Madrid between the 30th May and the 1st June, APIdays Mediterránea, a conference centered exclusively on the development and architecture of APIs, took place. Plenty of talks were given on the API ecosystem: from talks about the design of RESTful APIs to business talks about how to get the best out of an API. We were very lucky in that we had a great number of international speakers as well as Spanish speakers, who all came together to share their knowledge and experience.

On the first day, it was the Iberian Hackathon, a hackday centered on the development of applications surrounding APIs, in which I participated. The prizes were divided into categories according to the APIs used in the applications created. The sponsoring APIs were APIcultur, Mashape, XING and Twilio, although hackers could combine the APIs to create an application.

I competed in the XING category. For those who don’t know XING, it’s a social network for professionals, that enables you to network easily.

My first idea was to develop a mobile application for Android that would enable you to migrate your Linkedin contacts to XING So, after obtaining the list of your Linkedin contacts, they will move over to XING; in the event of the contact not having a XING profile, it would send an email invitation to them asking them to join the network, or otherwise, it would send the request directly.

Unfortunately, the API doesn’t provide, at the moment, a search for users by name, so I had to change my initial idea. After analysing the possibilities that the API offers in more depth, the application lists the email addresses of the contacts stored on your mobile phone and after pressing the “Send” button the application sends contact requests and email invitations.

Screenshot_2013-06-16-21-15-30Screenshot_2013-06-16-21-16-17Screenshot_2013-06-16-21-16-51Screenshot_2013-06-16-21-18-40Screenshot_2013-06-16-21-29-05

Let’s have a look at the implementation in more detail:

The XING API is REST and uses OAuth 1.0 in order to authenticate the user and give the application permission to access its data. So, in order to obtain a valid access token (necessary to carry out any request involving the API) the application should take the following steps:

  • Obtain a request token from the API.
  • Redirect the user to a link provided by the API, which will take them to a place where they will have to authenticate themselves and give permission to the app to access their information before being redirected back to the application.
  • Interchange the request token from the first step for the access token that has been returned.

To manage the flow I used the Java library scribe-java from @fernadezpablo that helps the work enormously, ince it abstracts all the logic mentioned and supports numerous OAuth APIs out-of-the-box, including the XING one.

So simple that it is configured in one line as shown below:

OAuthService service = new ServiceBuilder()
.provider(XingApi.class)
.apiKey("YOUR_API_KEY")
.apiSecret("YOUR_API_SECRET")
.build();

After this you obtain the request token:

Token requestToken = service.getRequestToken();
String authURL = service.getAuthorizationUrl(requestToken);

And load the link obtained in web view.

When you obtain the verifier (when the user logs into their account):

String verifier = uri.getQueryParameter("oauth_verifier");
Verifier v = new Verifier(verifier);

You obtain the access token:

Token accessToken = service.getAccessToken(requestToken, v);
String accessTokenXing = accessToken.getToken();
String accessSecretXing = accessToken.getSecret();

At this point you can request protected resources:

OAuthRequest request = new OAuthRequest(Verb.GET, PROTECTED_RESOURCE_URL);
service.signRequest(accessToken, request);

Be aware that you need to change the verb depending on the request you want to carry out.

In the end, you get the response and this is the information obtained (the requests return the results in JSON format):

Response response = request.send();
String result = response.getBody();

Curiously Javascript must be enabled on the web view for everything to work properly.

The developed application is based on the following requests for the API:

Look for users by email address (GET)

/v1/users/find_by_emails

It returns the list of users that coincides with the list of email addresses provided. In the event that the email address is not found on XING or is incorrect, it will return nothing.

Example of a response:

https://api.xing.com/v1/users/find_by_emails?emails=existing_user@xing.com,unknown_user@xing.com

{
"results": {
"items": [
{
"email": "existing_user@xing.com",
"hash": null,
"user": {
"id": "10368_ddec16"
}
},
{
"email": "unknown_user@xing.com",
"hash": null,
"user": null
}
],
"total": 2
}
}

Once this has been obtained users can make contact requests for users registered on XING (those who had id in the previous request) and for those who don’t have a profile, it sends an invitation by email to sign up for the network.

Iniciar petición de contacto (POST)

/v1/users/:user_id/contact_requests

Begin a contact request between the current user (sender) and the specified user (recipient).

Example:

https://api.xing.com/v1/users/3455987_6ae897/contact_requests

Send invitations (POST)

/v1/users/invite

Send invitations by email to contacts that don’t have a profile on XING. The user can send up to 2000 invitations per week. This call is currently in an EXPERIMENTAL phase.

Response example:

https://api.xing.com/v1/users/invite?to_emails=user1@example.com,user2@example.com&message=Join+XING+today&user_fields=id,display_name,permalink

{
"invitation_stats": {
"total_addresses": 7,
"invitations_sent": 3,
"already_invited": [
"kven.sever@example.net"
],
"already_member": [{
"id": "666666_abcdef",
"email": "sark.midt@xing.com",
"display_name": "Sark Midt"
}, {
"id": "12345_abcdef",
"email": "kennart.loopmann@xing.com",
"display_name": "Kennart Loopmann"
}],
"invalid_addresses": [
"@example.f"
]
}
}

For more information you can visit the XING developers’ portal:

https://dev.xing.com/

Finally, I would like to highlight the magnificent organisation of the event and encourage you to continue doing things like this. It is a very enriching experience that enables you to meet experts and gives you the opportunity to keep learning while doing what you like.

Author: Pablo Guardiola, Winner of the APIdays Mediterranea Iberic Hackathon in the XING category.
       Connect with Pablo on Twitter: @Guardiola31337
Share →