The service provides the functionality of a generic social network built around the SmartCommunity users. Using this service, the users may form communities, share and communicate information to other users, manage own social relations and scope the visibility of own data to those relations, etc.

For these purposes, the service relies on a simple yet expressive data model that contains:

• Users that operate their own data (user entities), social relations, perform individual social activities. When speaking about user social relations, we refer to
  • user groups (or circles in the terminology of, e.g., Google+), such as 'colleagues', 'family', 'friends', etc.
  • user communities, i.e., those communities that the user belongs to.
• Communities that group together different users on some common basis (e.g., students of the University or event students of the specific course). The communities also may have their own data that is available to the group members and can be shared with other communities or users.
• Entities (or object) that represent different forms of information in different applications. An important feature of these social entities that it the engine provides operations to annotate them with tags, relate to other objects (e.g., event object is related to a place object where it takes place, or photo is 'tagged' with the user on it), and finally shared with other users and/or communities.

The entities play the key role for the service clients as they allow for enabling social networking within applications. For example, an application managing personal course materials may exploit the service to create an entity for each of those materials and then allow the user to share it with classmates, search them, etc.

Below we present the details of the Data Model, the REST API of the service, and the Java client library that allows for accessing this data.

An important aspect referred to the community is that each community is provided with a unique identifier, which is created and registered through the Developer Console by a client application that manages the community. This allows for using the OAuth2.0 protocol and model to protect the community data and operations.

To register the community in the Developer Console, switch to the 'Permissions' tab in the client application configuration. Choose the 'Social networking service' and then the 'Own resources' tab. Add the new community specifying the value for its id. The authorization server will ensure that the specified value is unique, otherwise an error will be returned.

Note the created value for the community ID. It will be used in different API calls.

As described above the following data types form the data model of the service:

• User represents the SC user with the following fields (simiar to the basic profile):
  • name: user name (string);
  • surname: user surname (string);
  • socialId: an internal to this service identifier of the user (string);
  • id: a unique identifier that is used throughout the platform and the services to unambiguously refer to the specific user (string).
• Community represents the community of users and is identified with
  • name: community name (string);
  • socialId: an internal to this service identifier of the community (string);
  • id: a unique identifier that is used to globally identify the community and to manage the access control for its data (string);
  • tags: list of text-based or concept based annotations associated to the community (list of Concept instances).
• Entity represents the information entity of certain type and is defined with
  • entityId: a internal unique identifier of the entity (string);
  • entityType: a reference to the data type ID of the entity (string);
  • title: name of the entity (string);
  • description: textual description of the entity (string);
  • ownerId: reference to the socialId of the owning actor (user or community);
  • user: an object representing the owner (User instance). May be empty for certain scenarios;
  • tags: list of text-based or concept based annotations associated to the entity (list of Concept instances);
  • relations: list of ids of the entities, to which this one is related (list of string);
  • visibility: description of the entity visibility scope. That is, which other users, groups, communities, can see this entity (ShareVisibility instance);
  • creationDate: when the entity was created (timestamp).
• Group: represents the user-defined group of people (circles)
  • socialId: an internal to this service identifier of the group (string);
  • name: name of the group (string);
  • users: user that constitute this group (list of User instances);
• Concept: the generalized representation of the tag annotation. May define a simple text tag or more structured 'semantic' tag
  • id: id of the unique concept definition corresponding to this concept (string);
  • name: value for the text tag or name of the concept (string);
  • description: detailed definition of the semantic concept (string);
  • summary: short definition of the semantic concept (string).
• ShareVisibility represent the scope of the entity, i.e., which users/communities may read it.
  • allCommunities: true if the entity is visible by all the registered communities (boolean);
  • allUsers: true if the entity is visible by all the registered users (boolean);
  • allKnownCommunities: true if the entity will be shared with all the communities to which the current user participates (boolean);
  • allKnownUsers: true if the entity will be shared with all the users of all the user's groups (boolean);
  • userIds: list of specific users to share object with (list of users' social IDs);
  • communityIds: list of specific communities to share object with (list of communities' social IDs);
  • groupIds: list of specific groups to share object with (list of groups' social IDs).

Working with the service, the following functionalities are enabled through the APIs presented below.

It is possible for the user to organize its own social network. To accomplish this, the user can

• participate to different communities. The user can find the communities of interest and join or leave them.
• organize other people in own groups. The user can create and modify different groups (e.g., friends or family), add/remove people to/from these groups.

Social profile play important role when sharing the data as the user has the flexibility to decide the scope of the data visibility. That is, the data may be made public, available to a community, to all group members or even to a specific list of persons.

A specific application when necessary may create its own community (or event a set of communities). This is an important functionality when the application has a common social data that, however, should be restricted to only people that make part of a community.

Specifically, it is possible

• to create a new community restricting it to the specific application (via permission control);
• to delete a community;
• to list all the communities available in the platform.

The user may create different data entries that may be shared across the social network of the user. These entities may be of very different types (e.g., events, places, blog entries, etc.) and may originate from different applications. In a typical scenario, an application managing some data and willing to exploit the SmartCommunity social network functionality will create an entry in the social service and link it to its own data. Then the sharing operations are made available through these entries, while the app will be responsible for visualization of shared data.

The operations foreseen in this scenarios include

• creating, updating or deleting an entity providing its title, description, annotations (tags), and relations with other entities.
• read user objects filtering by type if needed.
• read objects shared with the user filtering by type or visibility scope.
• share / unshare objects with other members of the network.

Similar to the user data, it is possible to create different data entries for the community. These entities may be of very different types (e.g., events, places, blog entries, etc.) and may originate from different applications.

The operations foreseen in this scenarios include

• creating, updating or deleting an entity providing its title, description, annotations (tags), and relations with other entities.
• read community objects filtering by type if needed.
• read objects shared with the user filtering by type or visibility scope.
• share / unshare objects with other members of the network.

While the service already support some predefined data types, the applications may create new ones when necessary. These types should correspond to the well-defined concepts registered in the internal knowledge base. This knowledge base already contains a very large collection of concepts that are sufficient for accommodating literally arbitrary data types.

The scenarios relevant here include

• search for concepts by name or keyword;
• search existing types by name or concept;
• creation of new types if missing.

The below methods allow for managing user groups.

The request is emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.social

The method allows for creating a group for the current user.

Permission

socialservice.user.group.write

Parameters:

• Request body representing the group to be created (JSON object).

Request

POST /core.social/user/group HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
  name: "family"
}

Response

{
  name: "family",
  socialId : "123"
}

The method allows for updating a group for the current user.

Permission

socialservice.user.group.write

Parameters:

• groupId (path variable)
• Request body representing the group to be updated (JSON object).

Request

PUT /core.social/user/group/{groupId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
  name: "family"
  ...
}

Response true if the update was successful.

The method allows for deleting a group for the current user.

Permission

socialservice.user.group.write

Parameters:

• groupId (path variable)

Request

DELETE /core.social/user/group/{groupId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response true if the deletion was successful.

The method allows for adding users to a group for the current user.

Permission

socialservice.user.group.write

Parameters:

• groupId (path variable)
• userIds: list of users to be added

Request

PUT /core.social/user/group/{groupId}/members?userIds=123&userIds=456 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response true if the update was successful.

The method allows for removing users from a group for the current user.

Permission

socialservice.user.group.write

Parameters:

• groupId (path variable)
• userIds: list of users to be added

Request

DELETE /core.social/user/group/{groupId}/members?userIds=123&userIds=456 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response true if the update was successful.

The method allows for reading all the user groups.

Permission

socialservice.user.group.read

Request

GET /core.social/user/group HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
  content : [
    {
      name: "group1",
      socialId: "123"
      users: []
    },
    {
      name: "group2",
      socialId: "1234"
      users: []
    }
  ]
}

The method allows for reading a specific user group.

Permission

socialservice.user.group.read

Parameters

• groupId (path variable)

Request

GET /core.social/user/group/{groupId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
  name: "group1",
  socialId: "123"
  users: []
}

The below methods allow for adding/removing the current users to/from communities.

The request is emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.social

The method allows for adding the current user to a specific community.

Permission

socialservice.user.community.write

Parameters:

• cid (path variable): community Id

Request

PUT /core.social/user/community/{cid}
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response true if the update was successful.

The method allows for removing the current user from a specific community.

Permission

socialservice.user.community.write

Parameters:

• cid (path variable): community Id

Request

DELETE /core.social/user/community/{cid}
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response true if the update was successful.

The method allows for reading all the communities the user participates to.

Permission

socialservice.user.community.read

Request

GET /core.social/user/community HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
  content : [
    {
      id: "c1"
      name: "community 1",
      socialId: "123"
    },
    {
      id: "c2"
      name: "community 2",
      socialId: "456"
    }
  ]
}

The operations below provide the way to read and operate different communities. Note that to create/delete a community, the community should be registered in the Developer Console. This allows also to restrict the access to the community management only to its owner (or to the apps that obtained the corresponding permission).

The request is emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.social

The method allows for reading all the communities registered in the platform.

Permission

socialservice.community.all

Request

GET /core.social/community HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user or client access token}

Response

{
  content : [
    {
      id: "c1"
      name: "community 1",
      socialId: "123"
    },
    {
      id: "c2"
      name: "community 2",
      socialId: "456"
    }
  ]
}

The method allows for reading a specific community registered in the platform.

Permission

socialservice.community.all

Parameters

• cid (path variable): community ID

Request

GET /core.social/community/{cid} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user or client access token}

Response

{
  id: "c1"
  name: "community 1",
  socialId: "123"
}

The method allows for reading a specific community using its internal social ID.

Permission

socialservice.community.all

Parameters

• socialId (path variable): community social ID

Request

GET /core.social/community/social/{socialId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user or client access token}

Response

{
  id: "c1"
  name: "community 1",
  socialId: "123"
}

The method allows for creating a community.

Permission

socialservice.community.{cid}.write

Parameters

• cid (path variable): community ID as registered in Developer Console

Request

PUT /core.social/community/{cid} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
  id: "c1"
  name: "community 1"
}

Response

{
  id: "c1"
  name: "community 1",
  socialId: "123"
}

The method allows for deleting a community.

Permission

socialservice.community.{cid}.write

Parameters

• cid (path variable): community ID as registered in Developer Console

Request

DELETE /core.social/community/{cid} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response true if the operation was successful.

These operations provide CRUD operations over user data entities, data sharing, and access to the data shared with the user.

The request is emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.social

The method allows for creating an entity for the current user. The method takes as input the structure 'EntityRequest' with the following fields:

• type: name of the entity type, or
• typeId: id of the entity type
• name: title of the entity
• description: entity description
• tags: entity annotations (list of Concept instances)
• relations: entity relations

Permission

socialservice.user.entities.write

Parameters

• request body: entity request data structure

Request

POST /core.social/user/entities HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
  name:"my name",
  description: "description",
  typeId: "123",
  tags: [],
  relations:[]
}

Response: created entity

{
  entityId: "123",
  entityType: "123",
  title: "my name",
  description: "description"
  tags: [],
  relations:[],
  ownerId: "456",
  creationDate:  1234567789,
  user: null,
  visibility: null
}

The method allows for updating an entity for the current user. The method takes as input the structure 'EntityRequest' with the following fields:

• id: entity ID
• type: name of the entity type, or
• typeId: id of the entity type
• name: title of the entity
• description: entity description
• tags: entity annotations (list of Concept instances)
• relations: entity relations

Permission

socialservice.user.entities.write

Parameters

• entityId (path variable): id of the entity to be updated
• request body: entity request data structure

Request

PUT /core.social/user/entities/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
  id: "123", 
  name:"my name",
  description: "description",
  typeId: "123",
  tags: [],
  relations:[]
}

Response: true if the update was successful

The method allows for deleting an entity for the current user.

Permission

socialservice.user.entities.write

Parameters

• entityId (path variable): id of the entity to be updated

Request

DELETE /core.social/user/entities/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response: true if the delete was successful

The method allows for reading an entity for the current user.

Permission

socialservice.user.entities.read

Parameters

• entityId (path variable): id of the entity to read

Request

GET /core.social/user/entities/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
  entityId: "123",
  entityType: "123",
  title: "my name",
  description: "description"
  tags: [],
  relations:[],
  ownerId: "456",
  creationDate:  1234567789,
  user: {
    name: "Mario",
    surname: "Rossi",
    id: "1",
    socialId: "123"
  },
  visibility: {
    allUsers : false,
    allCommunities: false,
    allKnownUsers: true,
    allKnownCommunities: false,
    userIds:[],
    communityIds: [],
    groupIds: []
  }
}

The method allows for reading entities of the current user.

Permission

socialservice.user.entities.read

Parameters

• type: id of the entity type to filter (optional)
• position: position to take a subset from, defaults to 0
• size: number of entities to return. If not specified or negative, returns all

Request

GET /core.social/user/entities?type=123&position=10&size=10 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
  content: [
  {
    entityId: "123",
    entityType: "123",
    title: "my name",
    description: "description"
    tags: [],
    relations:[],
    ownerId: "456",
    creationDate:  1234567789,
    user: {
      name: "Mario",
      surname: "Rossi",
      id: "1",
      socialId: "123"
    },
    visibility: {
      allUsers : false,
      allCommunities: false,
      allKnownUsers: true,
      allKnownCommunities: false,
      userIds:[],
      communityIds: [],
      groupIds: []
    }
  },
  ...
  ]
}

The method allows for reading a specific entity shared with the current user.

Permission

socialservice.user.shared.read

Parameters

• entityId (path variable): id of the entity to read

Request

GET /core.social/user/shared/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
  entityId: "123",
  entityType: "123",
  title: "my name",
  description: "description"
  tags: [],
  relations:[],
  ownerId: "456",
  creationDate:  1234567789,
  user: {
    name: "Mario",
    surname: "Rossi",
    id: "1",
    socialId: "123"
  },
  visibility: null
}

The method allows for reading entities shared with the current user.

Permission

socialservice.user.shared.read

Parameters

• type: id of the entity type to filter (optional)
• position: position to take a subset from, defaults to 0
• size: number of entities to return. If not specified or negative, returns all
• request body: ShareVisibility instance to restrict the set of results to those that fall under the specified visibility scope.

Request

POST /core.social/user/shared?type=123&position=10&size=10 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
      allUsers : false,
      allCommunities: false,
      allKnownUsers: true,
      allKnownCommunities: false,
      userIds:[],
      communityIds: [],
      groupIds: []
}

Response

{
  content: [
  {
    entityId: "123",
    entityType: "123",
    title: "my name",
    description: "description"
    tags: [],
    relations:[],
    ownerId: "456",
    creationDate:  1234567789,
    user: {
      name: "Mario",
      surname: "Rossi",
      id: "1",
      socialId: "123"
    },
    visibility: null
  }  
  ...
  ]
}

The method allows for sharing an entity.

Permission

socialservice.user.shared.write

Parameters

• entityId (path variable): id of the entity
• request body: ShareVisibility instance to specify the target visibility scope.

Request

PUT /core.social/user/shared/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
      allUsers : false,
      allCommunities: false,
      allKnownUsers: true,
      allKnownCommunities: false,
      userIds:[],
      communityIds: [],
      groupIds: []
}

Response true if sharing operation was successful.

The method allows for unsharing an entity, i.e., making it visible only to the user itself.

Permission

socialservice.user.shared.write

Parameters

• entityId (path variable): id of the entity

Request

DELETE /core.social/user/shared/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response true if unsharing operation was successful.

These operations provide CRUD operations over community data entities, data sharing, and access to the data shared with the community. Note that the community should be registered in the Developer Console. This allows also to restrict the access to the community management only to its owner (or to the apps that obtained the corresponding permission).

The request is emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.social

The method allows for creating an entity for the community. The method takes as input the structure 'EntityRequest' with the following fields:

• type: name of the entity type, or
• typeId: id of the entity type
• name: title of the entity
• description: entity description
• tags: entity annotations (list of Concept instances)
• relations: entity relations

Permission

socialservice.community.{cid}.entities.write

Parameters

• cid (path variable): id of the community
• request body: entity request data structure

Request

POST /core.social/community/{cid}/entities HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
  name:"my name",
  description: "description",
  typeId: "123",
  tags: [],
  relations:[]
}

Response: created entity

{
  entityId: "123",
  entityType: "123",
  title: "my name",
  description: "description"
  tags: [],
  relations:[],
  ownerId: "456",
  creationDate:  1234567789,
  user: null,
  visibility: null
}

The method allows for updating an entity for the community. The method takes as input the structure 'EntityRequest' with the following fields:

• id: entity ID
• type: name of the entity type, or
• typeId: id of the entity type
• name: title of the entity
• description: entity description
• tags: entity annotations (list of Concept instances)
• relations: entity relations

Permission

socialservice.community.{cid}.entities.write

Parameters

• cid (path variable): id of the community
• entityId (path variable): id of the entity to be updated
• request body: entity request data structure

Request

PUT /core.social/commnunity/{cid}/entities/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
  id: "123", 
  name:"my name",
  description: "description",
  typeId: "123",
  tags: [],
  relations:[]
}

Response: true if the update was successful

The method allows for deleting an entity of the community.

Permission

socialservice.community.{cid}.entities.write

Parameters

• cid (path variable): id of the community
• entityId (path variable): id of the entity to be updated

Request

DELETE /core.social/community/{cid}/entities/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response: true if the delete was successful

The method allows for reading an entity of the community.

Permission

socialservice.community.{cid}.entities.read

Parameters

• cid (path variable): id of the community
• entityId (path variable): id of the entity to read

Request

GET /core.social/community/{cid}/entities/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
  entityId: "123",
  entityType: "123",
  title: "my name",
  description: "description"
  tags: [],
  relations:[],
  ownerId: "456",
  creationDate:  1234567789,
  user: null,
  visibility: {
    allUsers : false,
    allCommunities: false,
    allKnownUsers: true,
    allKnownCommunities: false,
    userIds:[],
    communityIds: [],
    groupIds: []
  }
}

The method allows for reading entities of the community.

Permission

socialservice.community.{cid}.entities.read

Parameters

• cid (path variable): id of the community
• type: id of the entity type to filter (optional)
• position: position to take a subset from, defaults to 0
• size: number of entities to return. If not specified or negative, returns all

Request

GET /core.social/community/{cid}/entities?type=123&position=10&size=10 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
  content: [
  {
    entityId: "123",
    entityType: "123",
    title: "my name",
    description: "description"
    tags: [],
    relations:[],
    ownerId: "456",
    creationDate:  1234567789,
    user: null,
    visibility: {
      allUsers : false,
      allCommunities: false,
      allKnownUsers: true,
      allKnownCommunities: false,
      userIds:[],
      communityIds: [],
      groupIds: []
    }},
  ...
  ]
}

The method allows for reading a specific entity shared with the community.

Permission

socialservice.community.{cid}.shared.read

Parameters

• cid (path variable): id of the community
• entityId (path variable): id of the entity to read

Request

GET /core.social/community/{cid}/shared/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
  entityId: "123",
  entityType: "123",
  title: "my name",
  description: "description"
  tags: [],
  relations:[],
  ownerId: "456",
  creationDate:  1234567789,
  user: {
    name: "Mario",
    surname: "Rossi",
    id: "1",
    socialId: "123"
  },
  visibility: null
}

The method allows for reading entities shared with the community.

Permission

socialservice.community.{cid}.shared.read

Parameters

• cid (path variable): id of the community
• type: id of the entity type to filter (optional)
• position: position to take a subset from, defaults to 0
• size: number of entities to return. If not specified or negative, returns all
• request body: ShareVisibility instance to restrict the set of results to those that fall under the specified visibility scope.

Request

POST /core.social/community/{cid}/shared?type=123&position=10&size=10 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
      allUsers : false,
      allCommunities: false,
      allKnownUsers: true,
      allKnownCommunities: false,
      userIds:[],
      communityIds: [],
      groupIds: []
}

Response

{
  content: [
  {
    entityId: "123",
    entityType: "123",
    title: "my name",
    description: "description"
    tags: [],
    relations:[],
    ownerId: "456",
    creationDate:  1234567789,
    user: {
      name: "Mario",
      surname: "Rossi",
      id: "1",
      socialId: "123"
    },
    visibility: null
  },
  ...
  ]
}

The method allows for sharing an entity.

Permission

socialservice.community.{cid}.shared.write

Parameters

• cid (path variable): id of the community
• entityId (path variable): id of the entity
• request body: ShareVisibility instance to specify the target visibility scope.

Request

PUT /core.social/community/{cid}/shared/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
      allUsers : false,
      allCommunities: false,
      allKnownUsers: true,
      allKnownCommunities: false,
      userIds:[],
      communityIds: [],
      groupIds: []
}

Response true if sharing operation was successful.

The method allows for unsharing an entity, i.e., making it visible only to the community itself.

Permission

socialservice.community.{cid}.shared.write

Parameters

• cid (path variable): id of the community
• entityId (path variable): id of the entity

Request

DELETE /core.social/community/{cid}/shared/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response true if unsharing operation was successful.

This API is used to search for entity types and if necessary create new ones. A typical scenario is when an application manages some specific data objects and wants to perform social operations over them. In this case, it is necessary to find a corresponding entity data type in the knowledge base and, if not present, create new one. Currently, to create an entity type it is necessary to find the corresponding concept in the knowledge base as the type represents in relation one-to-one.

The requests are emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.social

The method allows for searching concepts given a text prefix that is matched agains concept name.

Permission

socialservice.type.all

Parameters

• prefix: a prefix of the concept name to search
• maxResults: a maximum number of results to return

Request

GET /core.social/concept?prefix=test&maxResults=1 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client or user access token}

Response

{
  content: [
  {
    id: "5081",
    name: "test",
    summary: "mental measurement",
    description: "any standardized procedure for measuring sensitivity or memory or intelligence or aptitude or personality etc; \"the test was standardized on a large sample of students\""
  }
  ]
}

The method allows for searching types given a text prefix that is matched agains type name.

Permission

socialservice.type.all

Parameters

• prefix: a prefix of the type name to search
• maxResults: a maximum number of results to return

Request

GET /core.social/type?prefix=test&maxResults=1 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client or user access token}

Response

{
  content: [
  {
	id: "123",
	name: "test",
	concept: {
      id: "5081",
      name: "test",
      summary: "mental measurement",
      description: "any standardized procedure for measuring sensitivity or memory or intelligence or aptitude or personality etc; \"the test was standardized on a large sample of    students\""
    }
  }
  ]
}

The method allows for searching a type given the corresponding conceptId.

Permission

socialservice.type.all

Parameters

• conceptId (path variable): concept ID of the type

Request

GET /core.social/type/concept/{conceptId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client or user access token}

Response

  {
	id: "123",
	name: "test",
	concept: {
      id: "5081",
      name: "test",
      summary: "mental measurement",
      description: "any standardized procedure for measuring sensitivity or memory or intelligence or aptitude or personality etc; \"the test was standardized on a large sample of    students\""
    }
  }

The method allows for searching a type given the typeId.

Permission

socialservice.type.all

Parameters

• typeId (path variable): type ID of the type

Request

GET /core.social/type/{typeId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client or user access token}

Response

  {
	id: "123",
	name: "test",
	concept: {
      id: "5081",
      name: "test",
      summary: "mental measurement",
      description: "any standardized procedure for measuring sensitivity or memory or intelligence or aptitude or personality etc; \"the test was standardized on a large sample of    students\""
    }
  }

Allows for creating a type corresponding to a concept.

Permission

socialservice.type.all

Parameters

• conceptId: concept ID of the corresponding concept

Request

POST /core.social/type?conceptId=5081 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

  {
	id: "123",
	name: "test",
	concept: {
      id: "5081",
      name: "test",
      summary: "mental measurement",
      description: "any standardized procedure for measuring sensitivity or memory or intelligence or aptitude or personality etc; \"the test was standardized on a large sample of    students\""
    }
  }

The Social Service client library provides an access to the operations exposed by the Social Networking Service REST APIs.

The source code of the library is available at https://github.com/smartcampuslab/socialservice.client.

To use the library, one has to include the socialservice.client-2.0.jar, smartcampus.socialservice.model-2.0.jar, and smartcampus.client.commons-2.0.jar into the project classpath. Also, the Jackson library for JSON parsing is required. In case of Android application, the libraries should be placed into the libs folder. When Maven is used to manage project libraries, one can use the following dependency:

	<dependency>
		<groupId>eu.trentorise.smartcampus</groupId>
		<artifactId>socialservice.client</artifactId>
		<version>2.x</version>
		<scope>jar</scope>
	</dependency>

Note that the SmartCommunity repository should be included in Maven configuration, e.g.:

	<repository>
		<id>SmartCommunity</id>
		<url>http://repository.smartcampuslab.it/content/groups/public</url>
	</repository>

The functionality is exposed by the SocialService. The following code demonstrates how the classes may be used:

SocialService socialService  = new SocialServiceService("https://dev.smartcommunitylab.it/core.social");
 
// read concepts
Concepts concepts = socialService.getConceptByPrefix(Constants.USER_AUTH_TOKEN, "concert", 1);
Concept concept = concepts.getContent().get(0);
// read entity type
EntityType entityType = socialService.getEntityTypeByConceptId(Constants.USER_AUTH_TOKEN, concept.getId());
// read all user entities of that type
Entities entities = socialService.getUserEntities(Constants.USER_AUTH_TOKEN, null, null, entityType.getId());
 
// prepare entity request instance for creation
EntityRequest req = new EntityRequest();
req.setDescription("descr");
req.setName("name");
req.setTags(Collections.singletonList(test));
req.setTypeId(entityType.getId());
// create
Entity e = socialService.createUserEntity(Constants.USER_AUTH_TOKEN, req);
//...

The methods of the class correspond to different RESP API calls. More specifically:

• user groups API methods:
  • Groups getUserGroups(String token)
  • Group createUserGroup(String token, String name)
  • boolean updateUserGroup(String token, Group group)
  • boolean deleteUserGroup(String token, String groupId)
  • Group getUserGroup(String groupId, String token)
  • boolean addUsersToGroup(String groupId, List<String> userIds, String token)
  • boolean removeUsersFromGroup(String groupId, List<String> userIds, String token)
• user communities API methods:
  • Communities getUserCommunities(String token)
  • boolean addUserToCommunity(String token, String communityId)
  • boolean removeUserFromCommunity(String token, String communityId)
• community API methods:
  • Community getCommunity(String communityId, String token)
  • Community getCommunityBySocialId(String socialId, String token)
  • Communities getCommunities(String token)
  • Community createCommunity(String id, Community community, String token)
  • boolean deleteCommunity(String id, String token)
• user data API methods:
  • Entities getUserEntities(String token, Integer position, Integer size, String typeId)
  • Entity getUserEntity(String token, String entityId)
  • Entity createUserEntity(String token, EntityRequest entity)
  • boolean updateUserEntity(String token, EntityRequest entity)
  • boolean deleteUserEntity(String token, String entityId)
  • Entities getEntitiesSharedWithUser(String token, ShareVisibility shareVisibility, Integer position, Integer size, String typeId)
  • Entity getEntitySharedWithUser(String token, String entityId)
  • boolean shareUserEntity(String token, String entityId, ShareVisibility shareVisibility)
  • boolean unshareUserEntity(String token, String entityId)
• community data API methods:
  • Entities getCommunityEntities(String communityId, String token, Integer position, Integer size, String typeId)
  • Entity getCommunityEntity(String communityId, String token, String entityId)
  • Entity createCommunityEntity(String communityId, String token, EntityRequest entity)
  • boolean updateCommunityEntity(String communityId, String token, EntityRequest entity)
  • boolean deleteCommunityEntity(String communityId ,String token, String entityId)
  • Entities getEntitiesSharedWithCommunity(String communityId, String token, ShareVisibility shareVisibility, Integer position, Integer size, String typeId)
  • Entity getEntitySharedWithCommunity(String communityId, String token, String entityId)
  • boolean shareCommunityEntity(String communityId, String token, String entityId, ShareVisibility shareVisibility)
  • boolean unshareCommnunityEntity(String communityId, String token, String entityId)
• entity type API methods:
  • EntityType createEntityType(String token, String conceptId)
  • EntityType getEntityTypeById(String token, String entityTypeId)
  • EntityType getEntityTypeByConceptId(String token, String conceptId)
  • EntityTypes getEntityTypeByPrefix(String token, String prefix, Integer maxResults)
  • Concepts getConceptByPrefix(String token, String prefix, Integer maxResults)

~~DISQUS~~