Difference between revisions of "Social Networking Service"

From Gcube Wiki
Jump to: navigation, search
(→‎Service Overview)
Line 1: Line 1:
 
=Service Overview=
 
=Service Overview=
−
A subset of the social networking library functionalities is now reachable over http. Specifically, the interface allows to generate an application token by which an application is allowed to write on a certain vre and to perform this latter operation.
+
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 (BaseURL):
+
The Web Service Interface is hosted at the following address ('''Base_URL'''):
 +
 
 
https://dev.d4science.org/social-networking-library-ws/rest/
 
https://dev.d4science.org/social-networking-library-ws/rest/
  
−
Please note that only '''https''' may be used to access the Web Service Interface.
+
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==
 
== List of Available Functions==
−
* tokens/generateApplicationToken
+
* [[#Generate application token|Generate application token]]
−
* feeds/writeFeedApplication
+
* [[#Write application post|Write application post]] 
−
* feeds/getAllFeedsByApp
+
* [[#Retrieve all application feeds|Retrieve all application feeds]] 
 +
* [[#Retrieve all user feeds|Retrieve all user feeds]]
 +
* [[#Retrieve all user feeds since a given date|Retrieve all user feeds since a given date]]
 +
* [[#Retrieve all user feeds up to a given quantity|Retrieve all user feeds up to a given quantity]]
 +
* [[#Write user post|Write user post]] 
 +
* [[#Retrieve the identifiers of the feeds a user liked|Retrieve the identifiers of the feeds a user liked]]
 +
* [[#Retrieve the feeds a user liked|Retrieve the feeds a user liked]]
 +
* [[#Retrieve user's notifications in a given range|Retrieve user's notifications in a given range]]
 +
 
 +
== List of codes returned by the methods ==
  
 
== Usage ==
 
== Usage ==
  
−
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 in post in.
+
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.
−
Now, to get an ''application token'' you can invoke the first method. It is an HTTP/POST method, that accepts as parameters:
+
 
 +
=== Generate application token ===
 +
 
 +
The link to append to '''Base_URL''' is the following:
 +
 
 +
<source lang="html4strict">
 +
tokens/generateApplicationToken
 +
</source>
 +
 
 +
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;
 
* 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.
 
* token: a user token generated for the VRE in which you are interesting the application will write in.
  
−
You can call it by writing your own REST client application or by using (a lot of) already existent rest client plugins. For example, using the RESTClient plugin for Firefox you will have something like this for requiring a new application token:
+
For example, using the RESTClient plugin for Firefox you will have something like this for requiring a new application token:
  
 
[[File:GenerateApplicationToken.png]]
 
[[File:GenerateApplicationToken.png]]
Line 26: Line 46:
 
Push on the SEND button and if all it's ok, your application token will be generated and returned as result.
 
Push on the SEND button and if all it's ok, your application token will be generated and returned as result.
  
−
By means of this new token the application can write on the vre for which the token has been previously required. Just invoke the second method, that accepts these parameters:
+
=== Write application post ===
 +
 
 +
The link to append to '''Base_URL''' is the following:
 +
 
 +
<source lang="html4strict">
 +
feeds/writePostApplication
 +
</source>
 +
 
 +
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;  
 
* text: text of the post;  
Line 42: Line 70:
 
Push on SEND and check the result of the method.
 
Push on SEND and check the result of the method.
  
−
In order to retrieve all the feeds the application wrote (in every VRE it is allowed to write in) you can invoke the third (HTTP/GET) method. It accepts only one parameter:
+
=== Retrieve all application feeds ===
 +
The link to append to '''Base_URL''' is the following:
 +
 
 +
<source lang="html4strict">
 +
feeds/getAllFeedsByApp
 +
</source>
 +
 
 +
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.
 
* token: the only requirement is that it is a valid token for this application.
  
−
For example,  
+
For example, using your browser:
  
 
<source lang="html4strict">
 
<source lang="html4strict">
 
BASE_URL/feeds/getAllFeedsByApp?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy
 
BASE_URL/feeds/getAllFeedsByApp?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy
 +
</source>
 +
 +
=== Retrieve all user feeds ===
 +
The link to append to '''Base_URL''' is the following:
 +
 +
<source lang="html4strict">
 +
feeds/getAllFeedsByUser
 +
</source>
 +
 +
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:
 +
 +
<source lang="html4strict">
 +
BASE_URL/feeds/getAllFeedsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy
 +
</source>
 +
 +
=== Retrieve all user feeds since a given date ===
 +
The link to append to '''Base_URL''' is the following:
 +
 +
<source lang="html4strict">
 +
feeds/getRecentFeedsByUserAndDate
 +
</source>
 +
 +
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:
 +
 +
<source lang="html4strict">
 +
BASE_URL/feeds/getRecentFeedsByUserAndDate?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&time=xxxxx
 +
</source>
 +
 +
=== Retrieve all user feeds up to a given quantity ===
 +
The link to append to '''Base_URL''' is the following:
 +
 +
<source lang="html4strict">
 +
feeds/getRecentFeedsByUser
 +
</source>
 +
 +
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:
 +
 +
<source lang="html4strict">
 +
BASE_URL/feeds/getRecentFeedsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&quantity=20
 +
</source>
 +
 +
=== Write user post ===
 +
The link to append to '''Base_URL''' is the following:
 +
 +
<source lang="html4strict">
 +
feeds/writePostUser
 +
</source>
 +
 +
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:
 +
 +
[[File:Userpost.png]]
 +
 +
Push on SEND and check the result of the method.
 +
 +
=== Retrieve the identifiers of the feeds a user liked ===
 +
 +
The link to append to '''Base_URL''' is the following:
 +
 +
<source lang="html4strict">
 +
likes/getAllLikedFeedIdsByUser
 +
</source>
 +
 +
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:
 +
 +
<source lang="html4strict">
 +
BASE_URL/likes/getAllLikedFeedIdsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy
 +
</source>
 +
 +
=== Retrieve the feeds a user liked ===
 +
 +
The link to append to '''Base_URL''' is the following:
 +
 +
<source lang="html4strict">
 +
likes/getAllLikedFeedsByUser
 +
</source>
 +
 +
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:
 +
 +
<source lang="html4strict">
 +
BASE_URL/likes/getAllLikedFeedsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy
 +
</source>
 +
 +
===Retrieve user's notifications in a given range===
 +
 +
The link to append to '''Base_URL''' is the following:
 +
 +
<source lang="html4strict">
 +
notifications/getRangeNotificationsByUser
 +
</source>
 +
 +
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:
 +
 +
<source lang="html4strict">
 +
BASE_URL/notifications/getRangeNotificationsByUser?token=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyy&from=from&quantity=quantity
 
</source>
 
</source>

Revision as of 13:48, 21 December 2015

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

https://dev.d4science.org/social-networking-library-ws/rest/

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

List of codes returned by the methods

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.

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:

GenerateApplicationToken.png

Push on the SEND button and if all it's ok, your application token will be generated and returned as result.

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:

WriteApplicationPost.png

Push on SEND and check the result of the method.

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

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

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

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

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:

Userpost.png

Push on SEND and check the result of the method.

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

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

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
Retrieved from "https://wiki.gcube-system.org/index.php?title=Social_Networking_Service&oldid=23711"