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 https, thanks to a REST web service. The web service runs over SmartGears, so that authorization is transparently performed. SmartGears automatically publishes a Gcore EndPoint that contains information on how to reach the service.

The information needed to retrieve from the Information System the base url at which the web-service is reachable are these:

• Scope (in dev, the service is available in /gcube/devNext/NextNext)
• the service name: SocialNetworking
• service class: Portal

We will refer to this url as BASE_URL.

In the following the list of available functions and the parameters they need in order to be called are reported. They all require a gcube-token to perform authorization. See here for more information about this token. Please consider that 'token' and 'gcube-token' are the same thing, however in the following methods you must use gcube-token as parameter.

List of Available Functions

• Generate application gcube-token
• Write application post
• Retrieve all application posts
• Retrieve all user posts
• Retrieve all user posts since a given date
• Retrieve all user posts up to a given quantity
• Write user post
• Retrieve the identifiers of the posts a user liked
• Retrieve the posts a user liked
• Retrieve user's notifications in a given range
• Retrieve all vre posts
• Send a message

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 gcube-token for authentication purposes. You can get it using the Token Generator portlet available on the VRE you are interesting the app will post in. Now, to get an application gcube-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;
• gcube-token: a user token generated for the VRE in which you are interesting the application will write.

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 gcube-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:

posts/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];
• gcube-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 posts

The link to append to Base_URL is the following:

posts/getAllPostsByApp

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:

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

For example, using your browser:

BASE_URL/posts/getAllPostsByApp?gcube-token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

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

Retrieve all user posts

The link to append to Base_URL is the following:

posts/getAllPostsByUser

This HTTP/GET method accepts only one parameter:

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

For example, using your browser:

BASE_URL/posts/getAllPostsByUser?gcube-token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

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

Retrieve all user posts since a given date

The link to append to Base_URL is the following:

posts/getRecentPostsByUserAndDate

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:

• gcube-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/posts/getRecentPostsByUserAndDate?gcube-token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&time=xxxxx

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

Retrieve all user posts up to a given quantity

The link to append to Base_URL is the following:

posts/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:

• gcube-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/posts/getRecentFeedsByUser?gcube-token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&quantity=20

If all goes ok, the response object 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:

posts/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];
• gcube-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 posts a user liked

The link to append to Base_URL is the following:

likes/getAllLikedPostIdsByUser

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

• gcube-token: a valid user token.

Please note: the posts are not filtered for VRE.

For example, using your browser:

BASE_URL/likes/getAllLikedPostIdsByUser?gcube-token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

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

Retrieve the feeds a user liked

The link to append to Base_URL is the following:

likes/getAllLikedPostsByUser

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

• gcube-token: a valid user token.

Please note: the posts are not filtered for VRE.

For example, using your browser:

BASE_URL/likes/getAllLikedPostsByUser?gcube-token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

If all goes ok, the response object 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:

• gcube-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?gcube-token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&from=from&quantity=quantity

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

Retrieve all vre posts

The link to append to Base_URL is the following:

posts/getAllPostsByVRE

By means of this method a user that has a token valid for a certain VRE, can retrieve all the feeds of that VRE. The method requires a single parameter:

• gcube-token: a valid user token for the VRE from which the user wants to retrieve feeds.

For example, using your browser:

BASE_URL/posts/getAllPostsByVRE?gcube-token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy

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

Send a message

You can send a message via the web service by using one of the following POST methods:

• writeMessageToUsersUsingTokenSender;
• writeMessageToUsers.

The first one assumes that the sender is the owner of the passed gcube-token. With the other method, instead, by using your token you can also define who is going to be the sender of the message. Furthermore, according to the recipients' notifications preferences, they could receive a portal notification, a mail notification and so on.

Both methods require:

• gcube-token: a valid user's token;
• subject: the subject of the message to send;
• body: the body of the message;
• recipients: a list of valid comma separated users' ids (e.g., andrea.rossi, mario.rossi).

The second method also requires:

• sender: a valid sender's id.

An example usage of the first method is reported in the picture below:

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)