Social Navigation

From agINFRA

Jump to: navigation, search

Contents

Social Navigation

The Social Navigation Component provides the user with a navigation interface for
browsing through the content of interconnected repositories using a visualization of a thematic
ontology. The Social Navigation Component provides the user with a navigation interface for
browsing through the content of interconnected repositories using a visualization of a thematic
ontology. The agINFRA version of the component uses the recommendation component to interconnect resources based on annotations, such as ratings and tags, that runs in the grid in order to get fast and accurate results. The component also is deployed in the cloud, allowing users to get versions of the service without the need of installing and maintaining a local copy of the tool.

Responsible body(ies):

Usage and deployment (if publicly accessible)

The Social Navigation Service REST API for social data population and retrieval has been already developed. The new version is also connected with the recommender component. The component is currently deployed in a cloud service of GRNET. The agINFRA project is planning on signing a MoU with GRNET. If this is not done in the next period, a new image of the component will also be deployed in the agINFRA cloud.

The REST API of the social navigation service is presented here http://wiki.agroknow.gr/agroknow/index.php/Social_navigation_service_API#APIs.

Example Usage Scenario

Laura is a teacher that is interested in finding high quality learning content. She visits the Organic.Edunet learning portal and browse through the learning resources that are published in the portal. Nikos is the administrator of an agricultural learning portal. The portal provides access to learning resources and personalized functionalities such as my personal space where the user can see tags, ratings and bookmarks for the learning resources. Nikos has received the request from the owners of the portal to integrate suggestion services to the users based on social information that is collected. Nikos decides to include a service such as http://goo.gl/k5C71 which is provided through a web API and does not require the set up and configuration of a local database and mechanism to store the social data. The user personal information is stored only at the portal and the personal data in remote service is connected to the users only through an encoded code. The same service is providing suggestion services to the users based on the tags and the ratings that they have provided. Nikos would like to be able to have a look on all the social data that is collected for his portal and to monitor the performance of the recommendation algorithm. However, this is not provided by the service. Further, due to the fact that the social dataset is very dynamic the recommendation algorithms should be fine-tuned but this is not possible in the current version of the Social Navigation Service.

Before agINFRA

In the portal Laura can rate, tag learning resources, bookmark and to add a review for the resource. In addition, she has a personal space where she can view the tags, ratings and reviews for the learning resources. In this personal space the portal provides a list of suggested resources to Laura. However, sometimes she is not able to get suggestions due to lack of the social information needed to estimate a recommendation. In addition, Laura cannot have suggestions while viewing a resource. Nikos is using the Social Navigation Service provided through a web API for the Organic.Edunet portal. The social data (ratings, reviews and tags) that the users are providing are stored and the portal can retrieve them using specific methods of the web API. In addition to this, the service is providing suggestions to the user based on ratings and tags that have been provided by the users. However, the social navigation service currently has a number of limitations that can be summarized into the following points:

  • While the social data population and retrieval services works fine there are problems with the execution of the recommendation algorithms. This is due to the fact that the Virtual Machine in which the Social Navigation Service is installed cannot support computational intensive procedures like content based and collaborative filtering algorithms. This makes the recommendations not available and lowers the user experience.
  • In many cases recommendations are not available due to insufficient amount of the social data for a user, the well-known “cold start” problem. In this case other methodologies such as item-to-item collaborating filtering techniques could be explored and used by the Social Navigation Service. However, such methods are computational intensive and currently cannot be supported by the infrastructure used for Social Navigation Service.
  • Currently the Social Navigation Service is not able to provide suggestions to users that are not logged in. To address this recommendation methods based on the learning resource information e.g. title, keywords, could be implemented.
  • The usage information for the learning resources is important in order to understand what the users like and to provide meaningful suggestions. Currently the Social Navigation Service is not providing the ability to store usage data such as view, download, share and bookmark of a resource.
  • Nikos is not currently able to fine-tune the recommendation algorithm by changing the parameters of the recommendation algorithms such as the method for the formulation of the neighbourhood and the neighbourhood size in collaborative filtering algorithms. The performance of the recommendation algorithms highly depends on the selection of the best parameters for the specific dataset.
  • Nikos is not able to test his recommendation service or to perform any benchmarks before using the service. This is an important limitation because the performance of the suggestion services is a very critical issue before deciding to integrate them in the portal.
  • In the current version of the Social Navigation Service, Nikos is not able to browse through all the social data that was created by the users of the portal around the learning resources. Although such a service is simple to be set up it was avoided in order not to overload the Virtual Machine that is used for the service.

Most of the above limitations were not addressed until now due to the infrastructure limitations. Although some of the aforementioned processes are no so computational intensive running them on a Virtual Machine with basic characteristics would cause many performance issues.

agINFRA powered version

Enhance user experience

Laura is visiting the Organic.Edunet portal and is studying the content that matches her interests. She is able to download and share this resource with other users. While she is looking at a learning resource without being registered, the portal provides a list of suggested/related resources that are similar to the content that Laura is visiting (Figure 5.13). She is following the meaningful suggestions and this helps her in finding content that she can use in educational activities. Laura decides to register in order to get more personalized services. After the registration, she is able to tag and rate the learning resources as well as to put them in personal library for later use. The agINFRA powered Social Navigation Service is able to provide a list of suggested items also based on tags and ratings that she has provided.

The portal also provides to registered users like Laura a specific section with suggested resources based on what the user has viewed (browsing history), liked as well as based on the tags and ratings that she has provided. More specifically in this section Laura will be able to:

  • view suggested resources and mark some of them for later use
  • view resources that she has bookmarked for later use and marked as favourites.
  • remove resources from the list/carousel of the suggestions and in that case the portal will provide some new suggestions for her.

This personalized space of the portal will be divided into different sections such as “My favorites”, “History”, “For later” and “Suggested for you”. It also serves as a profile population activity as it asks users to rate or bookmark resources that they have not annoyed in the past. Cloud based admin panel for social services

Nikos became aware of the Social Navigation Service that is provided by agINFRA. He studies the web API provided by the service to populate and retrieve social and usage data as well as to get recommendations for the users. He also realizes that the Social Navigation Service is providing an admin and configuration panel that he can use to study the social data created by the users of his portal and to fine-tune the recommendation algorithms that he can use for the portal. The operation of the Social Navigation Services is supported by two parts: a) the recommender part that runs on the Grid and includes the computational and memory intensive algorithms for recommendations and b) the interface of the service that includes web interface and RESTful API to configure/monitor and consume the service, respectively. The first part corresponds to the Social Navigation Service.

Grid-based deployment of the recommendation engine

In order to support more sophisticated recommendation approaches that meet the users’ requirements, recommendation algorithms should be ported and run on the Grid infrastructure provided by the agINFRA. These recommendation services can be used both as individual service by anyone that would like to estimate recommendations for his data but also as part of the Cloud-based Social Navigation Service. The recommendation algorithms will run offline and will estimate user-based recommendations which will result in a set of recommended resources for each user but also item based recommendations which will result in a set of suggested resources related to a specific resource.

Content-based recommendations based on users’ tags and/or resources’ metadata can be also provided by the agINFRA Grid. Having a number of different recommendation algorithms will enable the provision of various suggestion services both to registered and non-registered users in the portal. The offline estimation of the recommendations for each user and resource e.g. every night, will address one of the basic limitations that the current version of the Social Navigation Service has which is the difficulty in providing recommendations in real time.

Grid-based social data facets

Even more the social navigation service can provide users with the ability of browsing resources based on social data facets. Applying facets is a very important task for limiting resources available in a data pool. The gain of Grid-based social data facets is the calculation of the facets on multiple computers and could be pre-calculated in multiple formats.

APIs

Social Navigation Service is a navigation interface component that allows for browsing through the content of interconnected repositories using a visualization of social annotations (such as ratings and tags). Here we present the RESTful API of the re-engineered Social Navigation Module. Since version 2.0, the web service is implemented using HTTP, the principles of REST and the JSON standard.


Authentication

Authentication is form-based for web interface and Basic for API. For Basic Authentication the header of request must contain -H "Authorization: Basic ?x?", where ?x? is base64 encode of username:password. For example the corresponding of “admin:admin” is “YWRtaW46YWRtaW4=”.


User Roles

Two user roles are registered and managed by applicationContext-security.xml. ROLE_ADMIN (admin:admin), who has access in web interface and api controllers and ROLE_REST_API (api:key), who has access only in api controllers. (www.domain.com/socnav/api/*)


Entities of Service

The main entities of the service are the followings:

  • Rating
  • Tagging
  • Reviewing
  • Accessing (New)

Thus, the web service is organized around these entities using the principles of REST.

Other secondary entities are:

  • User
  • Item
  • Tag
  • Preference

The diagram below presents the relationship graph between the entities. The concept is simple: Each of the main entities {Rating, Tagging, Reviewing} HasOne User and HasOne Item. Additionally a Rating HasMany Preference(s)
Social navigation service.png


Metadata Schema Definition

All event types extend the general metadata schema of Event, which is described below

Field

Datatype / Value

Description
id integer (Autogenerated) Identifier
domain string The domain
ip_address string Event session related ip address
session_id string Event session related id
updated_at SimpleDateFormat 1 Date of last update 
sharing_level enum {Public, Private} Wheather teh event is publicly available or a private one
item item type The item related to the event
user user type The user related to the event
version integer (Initial is 0).  The update version of the event. 

1 Java SimpleDateFormat, check docs.oracle.com/javase/1.4.2/docs/api/java/text/SimpleDateFormat.html

Here are some example of the entities:

  • Rating Entity
{
"id":42,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42",
"resourtce_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"preferences":
[
{"dimension":1, "value":2.0},
{"dimension":2, "value":4.0}
],
"preference_avg":3.0,
"version":0
}
  • Tagging Entity
{
"id":43,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42",
"resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"tags":
[
{"value":"επιμορφωτικό","lang":"el"},
{"value":"educational","lang":"en"}
],
"version":0
}
  • Reviewing Entity
{
"id":44,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42",
"resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"review":"This item is educational",
"lang":"en",
"version":0
}


RESTful API HTTP methods

Important note: Population methods are available only for the main entities. Secondary entities are populated only via the population methods of the main entities, an action that the system is responsible for.


Ratings

API Cheatsheat
Resource GET PUT POST DELETE
Collection URI
/socnav/api/ratings
List the members of the ratings. Available parameters:
userRemoteId, itemResourceUri, start, max
Not used Create a new rating in the collection where the ID will be generated automatically by the collection Not used
Member URI
/socnav/api/ratings/id
Retrieve the addressed rating with id=id (e.g. 42) Update the addressed rating with id=id (e.g. 42) Not used Delete the addressed rating with id=id (e.g. 42)


Get specific Rating

To retrieve a specific Rating, perform a GET operation at the Rating's URL.

GET Rating
Method Request URI
GET socnav/api/ratings/{id}
Parameters
Parameter Description
id The unique identifier of the rating (Integer)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/ratings/2
Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT {

domain: null,
id: 2,
ip_address: null,
item:
{
id: 2,
metadata_uri: null,
resource_id: null,
resource_uri: "1",
version: 0
},
preference_avg: 3,
preference_dimensions: 1,
preferences:[
{dimension: 1,
id: 3,
value: 3,
version: 0
}
],
session_id: null,
sharing_level: "Public",
updated_at: 1356195586000,
user:
{
id: 2,
metadata_uri: null,
remote_id: 1,
version: 0
},
version: 0}


List Ratings

To list Ratings, perform a GET operation at the Ratings' URL

List Ratings
Method Request URI
GET socnav/api/ratings/?param1=value1&param2=value2
Parameters
Parameter Description
userRemoteId Returns the Ratings of the addressed User with the remote unique identifier (Integer)
itemResourceUri Returns the Ratings of the addressed Item with the uri of the resource (String)
start Start position of the results (default=0)
max Set the max results (default=5)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/ratings?remoteUserId=5
Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT
[

{
domain: null,
id: 2,
ip_address: null,
item:{id: 2,
metadata_uri: null,
resource_id: null,
resource_uri: "1",
version: 0
},
preference_avg: 3,
preference_dimensions: 1,
preferences:
[
{
dimension: 1,
id: 3,
value: 3,
version: 0
}
],
session_id: null,
sharing_level: "Public",
updated_at: 1356195586000,
user:
{
id: 2,
metadata_uri: null,
remote_id: 1,
version: 0
},
version: 0}


.
.
. }]


Update specific Rating

To update a specific Rating, perform a PUT operation at the Rating's URL
Note:Old preferences are deleted and only new preferences are stored.

Update Rating
Method Request URI
PUT socnav/api/ratings/
Parameters
Parameter Description
Example
Request curl -i -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" -d '{"domain":null,"id":2,"ip_address":null,"item":{"id":2,"metadata_uri":null,"resource_id":null,"resource_uri":"1","version":0},"preference_avg":3.0,"preference_dimensions":1,"preferences":[{"dimension":1,"value":4.0}],"session_id":null,"sharing_level":"Public","updated_at":1356195586000,"user":{"id":2,"metadata_uri":null,"remote_id":1,"version":0},"version":0}' http://xxx.xxx.xxx.xxx/socnav/api/ratings
Request (human readable)

PUT /socnav/api/ratings/

Content-Type: application/json Accept: application/json Authorization: Basic YXBpOmtleQ==

{

"id":42,
"domain":"NewDomain.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"preferences":
[
{"dimension":1, "value":2.0},
{"dimension":2, "value":4.0}
],
"preference_avg":3.0,
"version":0

}

Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT


Create new Rating

To create a new Rating in the collection where the id will be generated automatically by the collection, perform a POST operation at the Ratings' URL

Create Rating
Method Request URI
POST socnav/api/ratings/
Parameters
Parameter Description
Example
Request curl -i -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" -d '{"domain":"foo.com","ip_address":"0.0.0.0","session_id":"b3258f85j","sharing_level":"Public","updated_at":1349523971000,"item":{"metadata_uri":"some.thing.org/uri42","resource_uri":"www.bar.com/video1"},"user":{"metadata_uri":null,"remote_id":55},"tags":[{"value":"επιμορφωτικό","lang":"el"},{"value":"educational","lang":"en"}]}'
http://xxx.xxx.xxx.xxx/socnav/api/ratings
Request (human readable)

POST /socnav/api/taggings/


Content-Type: application/json
Accept: application/json
Authorization: Basic YXBpOmtleQ==

{
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42",
"resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"tags":
[
{"value":"επιμορφωτικό","lang":"el"},
{"value":"educational","lang":"en"}
]
}

Response

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT


Delete Rating

To delete a specific Rating, perform a DELETE operation at the Rating's URL

Delete Rating
Method Request URI
DELETE socnav/api/ratings/{id}
Parameters
Parameter Description
id The unique identifier of the rating (Integer)
Example
Request curl -i -X DELETE -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/ratings/2
Response

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT


Taggings

API Cheatsheat
Resource GET PUT POST DELETE
Collection URI
/socnav/api/taggings
List the members of the taggings.Available parameters:
userRemoteId, itemResourceUri, tag, start, max
Not used Create a new tagging in the collection where the ID will be generated automatically by the collection. Not used
Member URI
/socnav/api/taggings/id
Retrieve the addressed tagging with id=id (e.g. 42) Update the addressed tagging with id=id (e.g. 42) Not used Delete the addressed tagging with id=id (e.g. 42)


Get specific Tagging

To retrieve a specific Tagging, perform a GET operation at the Tagging’s URL

GET Tagging
Method Request URI
GET socnav/api/taggings/{id}
Parameters
Parameter Description
id The unique identifier of the tagging (Integer)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/taggings/6
Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT

{

"id":43,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"tags":
[
{"value":"επιμορφωτικό","lang":"el"},
{"value":"educational","lang":"en"}
],
"version":0

}


List Taggings

To list Taggings, perform a GET operation at the Taggings’ URL

List Taggings
Method Request URI
GET /socnav/api/taggings/?param1=value1&param2=value2&param3=value3
Parameters
Parameter Description
userRemoteId Returns the Taggings of the addressed User with the remote unique identifier (Integer)
itemResourceUri Returns the Taggings of the addressed Item with the uri of the resource (String)
tag Returns the Taggings having the tag value=tag (String)
start Start position of the results (default=0)
max Set the max results (default=5)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/taggings?userRemoteId=7
Response

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT [

{
"id":43,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":7},
"tags":
[
{"value":"επιμορφωτικό","lang":"el"},
{"value":"educational","lang":"en"}
],
"version":0
},
{
"id":44,
"domain":"foo.com",
"ip_address":"2.2.2.2",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":7},
"tags":
[
{"value":"agricultural","lang":"en"}
],
"version":0
}

]


Update specific Tagging

To update a specific Tagging, perform a PUT operation at the Tagging's URL
Note:Old tags are deleted and only new preferences are stored.

Update Tagging
Method Request URI
PUT socnav/api/taggings/
Parameters
Parameter Description
Example
Request curl -i -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" -d '{"domain":null,"id":2,"ip_address":null,"item":{"resource_uri":"some_uri.com"},"session_id":null,"sharing_level":"Public","tags":[{"frequency":null,"lang":"el","value":"καλό"},{"frequency":null,"lang":"el","value":"καλό"},{"frequency":null,"lang":"el","value":"καλό"},{"frequency":null,"lang":"en","value":"organic power"}],"updated_at":1366749747000,"user":{"remote_id":1},"version":0}' http://xxx.xxx.xxx.xxx/socnav/api/taggings
Request (human readable)

PUT /socnav/api/taggings/

Content-Type: application/json Accept: application/json Authorization: Basic YXBpOmtleQ== {

"id":43,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"resource_uri":"www.bar.com/video1"},
"user":{"remote_id":55},
"tags":
[
{"value":"επιμορφωτικό","lang":"el"},
{"value":"educational","lang":"en"}
],
"version":0

}

Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=2D58F51D4417C1197F59D6B3D0D94232; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:19:09 GMT


Create new Tagging

To create a new Tagging in the collection where the id will be generated automatically by the collection, simply perform a POST operation at the Taggings' URL

Create Tagging
Method Request URI
POST socnav/api/taggings/
Parameters
Parameter Description
Example
Request

curl -i -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" -d '{"domain":"foo.com","ip_address":"0.0.0.0","session_id":"b3258f85j","sharing_level":"Public","updated_at":1349523971000,"item":{"metadata_uri":"some.thing.org/uri42","resource_uri":"www.bar.com/video1"},"user":{"metadata_uri":null,"remote_id":55},"tags":[{"value":"επιμορφωτικό","lang":"el"},{"value":"educational","lang":"en"}]}' http://xxx.xxx.xxx.xxx/socnav/api/taggings

Request (human readable)

PPOST /socnav/api/taggings/

Content-Type: application/json Accept: application/json Authorization: Basic YXBpOmtleQ== {

"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"tags":
[
{"value":"επιμορφωτικό","lang":"el"},
{"value":"educational","lang":"en"}
]

}

Response

HTTP/1.1 201 Created Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=8146141833B5886644F01F9A030D5399; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:48:28 GMT


Delete Tagging

To delete a specific Tagging, perform a DELETE operation at the Tagging's URL

Delete Tagging
Method Request URI
DELETE socnav/api/taggings/{id}
Parameters
Parameter Description
id The unique identifier of the Tagging (Integer)
Example
Request curl -i -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/taggings/2
Response

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=261B5813D158D81BD20E0DFE9FCBCBB2; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:25:42 GMT


Reviewings

API Cheatsheat
Resource GET PUT POST DELETE
Collection URI
/socnav/api/reviewings
List the members of the reviewings. Available parameters:
userRemoteId, itemResourceUri, start, max
Not used Create a new Reviewing in the collection where the ID will be generated automatically by the collection Not used
Member URI
/socnav/api/reviewings/id
Retrieve the addressed Reviewing with id=id (e.g. 42) Update the addressed Reviewing with id=id (e.g. 42) Not used Delete the addressed Reviewing with id=id (e.g. 42)


Get specific Reviewing

To retrieve a specific Reviewing , perform a GET operation at the Reviewing's URL.

GET Reviewing
Method Request URI
GET socnav/api/reviewings/{id}
Parameters
Parameter Description
id The unique identifier of the Reviewing (Integer)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/reviewings/33
Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=13B0FC3FDC120B3DBE9E0338AACAE48C; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 352 Date: Wed, 29 May 2013 23:37:22 GMT {

"domain":null,
"id":33,
"ip_address":null,
"item":
{
"id":8,
"metadata_uri":null,
"resource_id":null,
"resource_uri":"http://oe.confolio.org/scam/29/entry/90",
"version":0
},
"lang":"en",
"review":"very good resource",
"session_id":null,
"sharing_level":"Public",
"updated_at":1356195772000,
"user":
{
"id":8,
"metadata_uri":null,
"remote_id":63,
"version":0
},
"version":0

}


List Reviewings

To list Reviewings, perform a GET operation at the Ratings' URL

List Reviewings
Method Request URI
GET socnav/api/reviewings/?param1=value1&param2=value2
Parameters
Parameter Description
userRemoteId Returns the Reviewings of the addressed User with the remote unique identifier (Integer)
itemResourceUri Returns the Reviewings of the addressed Item with the uri of the resource (String)
start Start position of the results (default=0)
max Set the max results (default=5)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socn/api/reviewings?userRemoteId=63
Response

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT [

{
"id":53,
"domain":"domain.com",
"ip_address":"5.5.5.5",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.foo.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"review":"This item is educational",
"lang":"en",
"version":0
},
{
"id":66,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"review":"Αρκετά καλό για μάθημα βιολογίας",
"lang":"el",
"version":0
}

]


Update specific Reviewing

To update a specific Reviewing, perform a PUT operation at the Rating's URL
Note:Old preferences are deleted and only new preferences are stored.

Update Reviewing
Method Request URI
PUT socnav/api/reviewings/
Parameters
Parameter Description
Example
Request curl -i -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" -d '{domain: null,id: 33,ip_address: null,item: {resource_uri: "http://oe.confolio.org/scam/29/entry/90",version: 0},lang: "en",review: "veryresource",session_id: null,sharing_level: "Public",updated_at: 1356195772000,user: {remote_id: 63,version: 0},version: 0}' http://xxx.xxx.xxx.xxx/socnav/api/reviewings

Request (human readable)

PUT /socnav/api/reviewings/

Content-Type: application/json Accept: application/json Authorization: Basic YXBpOmtleQ== {

"id":43,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"review":"This item is educational",
"lang":"en",
"version":0

}

Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=2D58F51D4417C1197F59D6B3D0D94232; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:19:09 GMT


Create new Reviewing

To create a new Reviewing in the collection where the id will be generated automatically by the collection, perform a POST operation at the Ratings' URL

Create Reviewing
Method Request URI
POST socnav/api/reviewings/
Parameters
Parameter Description
Example
Request curl -i -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" -d '{"domain":"foo.com","ip_address":"0.0.0.0","session_id":"b3258f85j","sharing_level":"Public","updated_at":1349523971000,"item":{"metadata_uri":"some.thing.org/uri42","resource_uri":"www.bar.com/video1"},"user":{"metadata_uri":null,"remote_id":55},"review":"This item is educational","lang":"en"}' http://xxx.xxx.xxx.xxx/socnav/api/reviewings
Request (human readable)

POST /socnav/api/reviewings/

Content-Type: application/json Accept: application/json Authorization: Basic YXBpOmtleQ== {

"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"review":"This item is educational",
"lang":"en"

}

Response

HTTP/1.1 201 Created Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=8146141833B5886644F01F9A030D5399; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:48:28 GMT


Delete Reviewing

To delete a specific Reviewing, perform a DELETE operation at the Rating's URL

Delete Reviewing
Method Request URI
DELETE socnav/api/ratings/{id}
Parameters
Parameter Description
id The unique identifier of the Reviewing (Integer)
Example
Request curl -i -X DELETE -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/reviewings/82
Response

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=261B5813D158D81BD20E0DFE9FCBCBB2; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:25:42 GMT


Accessings (New!)

API Cheatsheat
Resource GET PUT POST DELETE
Collection URI
/socnav/api/accessings
List the members of the accessings. Available parameters:
userRemoteId, itemResourceUri, start, max
Not used Create a new Accessing in the collection where the ID will be generated automatically by the collection Not used
Member URI
/socnav/api/accessings/id
Retrieve the addressed Accessing with id=id (e.g. 42) Update the addressed Accessing with id=id (e.g. 42) Not used Delete the addressed Accessing with id=id (e.g. 42)


Get specific Accessing

To retrieve a specific Accessing , perform a GET operation at the Accessing's URL.

GET Accessing
Method Request URI
GET socnav/api/accessings/{id}
Parameters
Parameter Description
id The unique identifier of the Accessing (Integer)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/accessings/33
Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=13B0FC3FDC120B3DBE9E0338AACAE48C; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 352 Date: Wed, 29 May 2013 23:37:22 GMT {

"domain":null,
"id":33,
"ip_address":null,
"item":
{
"id":8,
"metadata_uri":null,
"resource_id":null,
"resource_uri":"http://oe.confolio.org/scam/29/entry/90",
"version":0
},
"session_id":null,
"sharing_level":"Public",
"updated_at":1356195772000,
"user":
{
"id":8,
"metadata_uri":null,
"remote_id":63,
"version":0
},
"version":0

}


List Accessings

To list Accessings, perform a GET operation at the Ratings' URL

List Accessings
Method Request URI
GET socnav/api/accessings/?param1=value1&param2=value2
Parameters
Parameter Description
userRemoteId Returns the Accessings of the addressed User with the remote unique identifier (Integer)
itemResourceUri Returns the Accessings of the addressed Item with the uri of the resource (String)
start Start position of the results (default=0)
max Set the max results (default=5)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socn/api/accessings?userRemoteId=63
Response

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT [

{
"id":53,
"domain":"domain.com",
"ip_address":"5.5.5.5",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.foo.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"version":0
},
{
"id":66,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"version":0
}

]


Update specific Accessing

To update a specific Accessing, perform a PUT operation at the Rating's URL
Note:Old preferences are deleted and only new preferences are stored.

Update Accessing
Method Request URI
PUT socnav/api/accessings/
Parameters
Parameter Description
Example
Request curl -i -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" -d '{domain: null,id: 33,ip_address: null,item: {resource_uri: "http://oe.confolio.org/scam/29/entry/90",version: 0},lang: "en",review: "veryresource",session_id: null,sharing_level: "Public",updated_at: 1356195772000,user: {remote_id: 63,version: 0},version: 0}' http://xxx.xxx.xxx.xxx/socnav/api/accessings

Request (human readable)

PUT /socnav/api/accessings/

Content-Type: application/json Accept: application/json Authorization: Basic YXBpOmtleQ== {

"id":43,
"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},
"version":0

}

Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=2D58F51D4417C1197F59D6B3D0D94232; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:19:09 GMT


Create new Accessing

To create a new Accessing in the collection where the id will be generated automatically by the collection, perform a POST operation at the Ratings' URL

Create Accessing
Method Request URI
POST socnav/api/accessings/
Parameters
Parameter Description
Example
Request curl -i -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpOmtleQ==" -d '{"domain":"foo.com","ip_address":"0.0.0.0","session_id":"b3258f85j","sharing_level":"Public","updated_at":1349523971000,"item":{"metadata_uri":"some.thing.org/uri42","resource_uri":"www.bar.com/video1"},"user":{"metadata_uri":null,"remote_id":55},"review":"This item is educational","lang":"en"}' http://xxx.xxx.xxx.xxx/socnav/api/accessings
Request (human readable)

POST /socnav/api/accessings/ Content-Type: application/json Accept: application/json Authorization: Basic YXBpOmtleQ== {

"domain":"foo.com",
"ip_address":"0.0.0.0",
"session_id":"b3258f85j",
"sharing_level":"Public",
"updated_at":1349523971000,
"item":{"metadata_uri":"some.thing.org/uri42", "resource_uri":"www.bar.com/video1"},
"user":{"metadata_uri":null,"remote_id":55},

}

Response

HTTP/1.1 201 Created Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=8146141833B5886644F01F9A030D5399; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:48:28 GMT


Delete Accessing

To delete a specific Accessing, perform a DELETE operation at the Rating's URL

Delete Accessing
Method Request URI
DELETE socnav/api/ratings/{id}
Parameters
Parameter Description
id The unique identifier of the Accessing (Integer)
Example
Request curl -i -X DELETE -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/accessings/82
Response

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=261B5813D158D81BD20E0DFE9FCBCBB2; Path=/socnav/api/; HttpOnly Content-Type: application/json;charset=UTF-8 Content-Length: 0 Date: Wed, 29 May 2013 19:25:42 GMT


Users

To retrieve a specific User, perform a GET operation at the Users’ URL

GET User
Method Request URI
GET /socnav/api/users/?user_remote_id=id&param1=value1&param2=value2&param3=value3&param4=value4
Parameters
Parameter Description
remoteId (mandatory)The remote unique identifier of the user (Integer)
withTags Returns list of tag values that this user has put (Boolean)
withRecommendations Returns list of recommended items, maximum 5 items, for this user (Boolean)
start Start position of the results (Default=0)
max Set the max results (Default=5)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/users?remoteId=55&withTags=true
Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=DAC89E2D02AF6A0EC161DD58F38CB658; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 56 Date: Wed, 29 May 2013 23:59:33 GMT

{

id: 42,
metadata_uri: null,
remote_id: 55,
tags: [
{
frequency: 1,
lang: null,
value: "επιμορφωτικό"
},
{
frequency: 1,
lang: null,
value: "educational"
}
],
version: 0

}


Items


Get Item

To retrieve a specific Item, perform a GET operation at the Item’s URL

GET Item
Method Request URI
GET /socnav/api/items/?resource_uri=”some_uri”&param1=value1
Parameters
Parameter Description
resourceUri (mandatory)The resource uri of the item (String)
resourceId The resource id of the Item (String)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/items?resourceUri=www.bar.com/video1
Response HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=FC7862E6D359C810DFFD6108CDB77553; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 213 Date: Thu, 30 May 2013 00:02:06 GMT {

"id":265,
"metadata_uri":"some.thing.org/uri42",
"resource_id":null,
"resource_uri":"www.bar.com/video1",
"tags":[
{
"frequency":1,
"value":"?π??????????"
},
{
"frequency":1,
"value":"educational"
}
],
"version":0

}


List Items

To retrieve a list of Items, perform a GET operation at the Items’ URL

List Items
Method Request URI
GET /socnav/api/items/?param1=value1&param2=value2&param3=value3
Parameters
Parameter Description
tag Returns list of Items which have been annotated with the tag (String)
lang Must accompanying tag param. Permitted values: Iso code values. en, el, de, etc...
popular Returns list of Items having the highest mean rating (Boolean, default value set to false)
start Start position of the results (Default=0)
max Set the max results (Default=5)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/items?tag=educational&lang=en
Response

Server: Apache-Coyote/1.1 Set-Cookie: JSESSIONID=ECCE962773CE0EBE641CA38173533B22; Path=/socnav Content-Type: application/json;charset=utf-8 Content-Length: 598 Date: Thu, 30 May 2013 00:02:55 GMT [

{
id: 265,
metadata_uri: "some.thing.org/uri42",
resource_id: null,
resource_uri: "www.bar.com/video1",
tags: [
{
frequency: 1,
value: "?π??????????"
},
{frequency: 1,
value: "educational"
}
],
version: null}]


Tags

To retrieve a list of tags along with the number of times each one has been used in distinct taggings(frequency), perform a GET operation at the Tags’ URL{| class="wikitable" |+ style="text-align:left"| GET Tags |-style="font-style: italic; color: white; background-color:blue;" |Method||Request URI |-style="font-style: italic; color: black; background-color:white;" |style=white-space:nowrap|GET||/socnav/api/tags/?param1=value1 |}

Parameters
Parameter Description
lang (mandatory)The lang of the tag (String)
resourceUri (mandatory)The resource uri of the item (String)
max Set the max results (Default=5)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/tags?lang=el
Response Server: Apache-Coyote/1.1

Set-Cookie: JSESSIONID=E5B4EEA621CBAAC4CAECB64DA78AB8EC; Path=/socnav Set-Cookie: locale=el; Path=/ Content-Type: application/json;charset=utf-8 Content-Length: 106 Date: Thu, 30 May 2013 00:04:35 GMT

[

{
"frequency":1,
"lang":"el",
"value":"foo"
},
{
"frequency":1,
"lang":"el",
"value":"επιμορφωτικό"
}

]


Recommendations

To retrieve list of recommendations - recommended items - for a user, perform a GET operation at the Recommendations’ URL

GET Recommendations
Method Request URI
GET /socnav/api/recommendations/?user_remote_id=id&param1=value1
Parameters
Parameter Description
userRemoteId The unique identifier of the user (Integer)
max The limit of the list (Integer)
Example
Request curl -i -X GET -H "Content-Type: application/json" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic YXBpOmtleQ==" http://xxx.xxx.xxx.xxx/socnav/api/recommendations/?user_remote_id=1&max=3
Response HTTP/1.1 200 OK

Content-Type: application/json;charset=utf-8 Content-Length: 206 Date: Sat, 06 Sep 2012 13:39:43 GMT

[

{
"item":
{
"metadata_uri":"some.thing.org/uri42",
"resource_uri":"www.bar.com/video1"
},
"estimation":3.0
},
{
"item":
{
"metadata_uri":"some.thing.org/uri55",
"resource_uri":"www.foo.com/image1"
},
"estimation":2.0
}

]

Personal tools