Social Networking Service

Service Overview

The Social Networking Library contains a set of functionalities to query a Cassandra Cluster. A subset of such functionalities is now reachable over http, thanks to a REST web service.

The Web Service Interface is hosted at the following address (Base_URL):

PORTAL/social-networking-library-ws/rest/

PORTAL can assume different values. For development use:

https://dev.d4science.org

Please note that only https may be used to access the Web Service Interface. In the following the list of available functions and the parameters they need in order to be called are reported.

List of Available Functions

• Generate application token
• Write application post
• Retrieve all application feeds
• Retrieve all user feeds
• Retrieve all user feeds since a given date
• Retrieve all user feeds up to a given quantity
• Write user post
• Retrieve the identifiers of the feeds a user liked
• Retrieve the feeds a user liked
• Retrieve user's notifications in a given range

Usage

The methods of the Web Service can be called by writing your own REST client application or by using (a lot of) already existent rest client plugins. In the following, we will use the RESTClient plugin for Firefox for POST methods. Your browser can be used for GET methods. The return value of each method is an HTTP Response object that has an HTTP CODE (200, 201, 400, 500, ...) and, optionally, a JSON or text object that represents the created/retrieved resource or better specifies the occurred error. In case of errors, please refer to the Troubleshooting section for more details.

Generate application token

The link to append to Base_URL is the following:

tokens/generateApplicationToken

First of all, you need to have a user token for authentication purposes. You can get it using the Service Authentication portlet available on the VRE you are interesting the app will post in. Now, to get an application token you can invoke the method. It is an HTTP/POST method that accepts as parameters:

• appid: the identifier of the application as reported in the Application Profile;
• token: a user token generated for the VRE in which you are interesting the application will write in.

For example, using the RESTClient plugin for Firefox you will have something like this for requiring a new application token:

Push on the SEND button and if all it's ok, your application token will be generated and returned as plain text in the response within the HTTP response having code 201.

Write application post

The link to append to Base_URL is the following:

feeds/writePostApplication

By means of the application token requested with the above method, the app can write on the VRE for which the token has been previously requested. Just invoke this method, that accepts these parameters:

• text: text of the post;
• params: additional parameters if your application supports the direct opening of of this update's object e.g. id=12345&type=foo [optional];
• previewtitle: a title for the preview of the post [optional];
• previewdescription: a description for the preview of the post [optional];
• httpimageurl: if you want to put an image, pass its url [optional];
• token: that must be a valid application token (likely generated by invoking the previous method);
• enablenotification: a boolean value to enable notifications [optional];

For example:

Push on SEND and check the code associated to the returned response (201 in case of success).

Retrieve all application feeds

The link to append to Base_URL is the following:

feeds/getAllFeedsByApp

In order to retrieve all the feeds the application wrote (in every VRE it is allowed to write in) you can invoke this HTTP/GET method. It accepts only one parameter:

• token: the only requirement is that it is a valid token for this application.

For example, using your browser:

BASE_URL/feeds/getAllFeedsByApp?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

If all goes ok, the response objects has status code 200 and the feeds are returned in JSON format.

Retrieve all user feeds

The link to append to Base_URL is the following:

feeds/getAllFeedsByUser

This HTTP/GET method accepts only one parameter:

• token: the only requirement is that it is a valid user token.

For example, using your browser:

BASE_URL/feeds/getAllFeedsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

If all goes ok, the response objects has status code 200 and the feeds are returned in JSON format.

Retrieve all user feeds since a given date

The link to append to Base_URL is the following:

feeds/getRecentFeedsByUserAndDate

If you are interested in retrieving user's feeds whose timestamps are greater than a given date you can invoke this method. This HTTP/GET method accepts two parameters:

• token: the only requirement is that it is a valid user token;
• time: the time of the oldest feed to retrieve converted in milliseconds.

For example, using your browser:

BASE_URL/feeds/getRecentFeedsByUserAndDate?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&time=xxxxx

If all goes ok, the response objects has status code 200 and the feeds are returned in JSON format.

Retrieve all user feeds up to a given quantity

The link to append to Base_URL is the following:

feeds/getRecentFeedsByUser

If you are interested in retrieving user's feeds, starting from the newest up to a given quantity you can invoke this method. This HTTP/GET method accepts two parameters:

• token: the only requirement is that it is a valid user token;
• quantity: a value greater than zero (the default value is 10).

For example, using your browser:

BASE_URL/feeds/getRecentFeedsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&quantity=20

If all goes ok, the response objects has status code 200 and the feeds are returned in JSON format.

Write user post

The link to append to Base_URL is the following:

feeds/writePostUser

By means of a valid user token, he/she can write on the VRE for which the token has been previously requested. Just invoke this method, that accepts these parameters:

• text: text of the post;
• previewtitle: a title for the preview of the post [optional];
• previewdescription: a description for the preview of the post [optional];
• previewHost: [optional];
• previewUrl: [optional];
• httpimageurl: if you want to put an image, pass its url [optional];
• token: that must be a valid user token;
• enablenotification: a boolean value to enable notifications [optional];

For example:

Push on SEND and check the code associated to the returned response (201 in case of success).

Retrieve the identifiers of the feeds a user liked

The link to append to Base_URL is the following:

likes/getAllLikedFeedIdsByUser

By means of this method a user can retrieve the identifiers of the feeds he/she liked. The method requires:

• token: a valid user token.

Please note: the feeds are not filtered for VRE.

For example, using your browser:

BASE_URL/likes/getAllLikedFeedIdsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

If all goes ok, the response objects has status code 200 and the identifiers of the feeds are returned in JSON format.

Retrieve the feeds a user liked

The link to append to Base_URL is the following:

likes/getAllLikedFeedsByUser

By means of this method a user can retrieve the feeds he/she liked. The method requires:

• token: a valid user token.

Please note: the feeds are not filtered for VRE.

For example, using your browser:

BASE_URL/likes/getAllLikedFeedsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

If all goes ok, the response objects has status code 200 and the feeds are returned in JSON format.

Retrieve user's notifications in a given range

The link to append to Base_URL is the following:

notifications/getRangeNotificationsByUser

By means of this method a user can retrieve his/her last notifications in the range [a, b]. The method requires:

• token: a valid user token.
• from: an integer greater than zero;
• quantity: an integer equal or greater than zero.

The final range is evaluated as [from, from + quantity]

For example, using your browser:

BASE_URL/notifications/getRangeNotificationsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&from=from&quantity=quantity

If all goes ok, the response objects has status code 200 and the feeds are returned in JSON format.

Troubleshooting

There could be many reasons for a failed request. Please always check the HTTP CODE and the message within the response.

This table tries to help you:

HTTP CODE	Meaning
400 - BAD_REQUEST	Please check the parameters you are passing
403 - FORBIDDEN	Is the token valid? / Does it belong to an application? [In case of application request]
404 - NOT_FOUND	The object(s) you are asking for is(are) not available
500 - INTERNAL_SERVER_ERROR	There was an error while serving your request (retry later)