This service endpoints aim at providing a way to handle the following kind of profiles tied to the registered users:

• a single Basic Profile per user, containing fundamental information (name, surname, socialId). This profile is read only.
• a single Account Profile per user, containing the accounts information (e.g., google account name). This profile is read only.
• multiple Extended Profiles per user, associated to a particular application and containing custom content (basically, a string to object map).

Any application can create and manage several extended profiles. To scope the access to a specific profile type, it is necessary to register the profile resource scope parameters in the developer console (section “Own resources”). The values are unique across all the SmartCommunity clients.

The service endpoints expose the following APIs:

• Retrieving the Basic Profile of the user doing the request, the Basic Profile of another users or all the Basic Profile (eventually filtering their name/surname).
• Retrieve the Account Profile of the current user.
• CRUD operations for Extended Profile, reading profile of a specific type, application, user. A user may share its Extended Profile instance with other users; for this purpose it is associated to a social entity ID to control the sharing process through the Social Service API.

The details of the Basic and Extended Profile REST API can be found here. The details of the Extended Profile REST API can be found here. The description of the Java client library can be found here.

The following data structures define the profile objects:

• BasicProfile:
  • name: user name (string);
  • surname: user surname (string);
  • socialId: an identifier of the user used in the Social / Semantic Engine to refer to the user, its data, and social model (string);
  • userId: a unique identifier that is used throughout the platform and the services to unambiguously refer to the specific user (string).
• AccountProfile:
  • accounts: map where the keys are the accounts (e.g., google, unitn) and values are the maps with the account attributes (key-value pairs).
• ExtendedProfile:
  • profileId: name of the single profile, used to distinguish different profiles for the same user/app;
  • content: arbitrary content (as key-value pairs);
  • userId, version, user, and updateTime as above.
  • socialId : an identifier of the extended profile entity used in the Social / Semantic Engine to refer to it.

The following operations are allowed for the basic profile endpoint:

• read basic profile of the current user. User access token is required.
• read account profile of the current user. User access token is required.
• read basic profile of any user given its ID or social ID, group of users (all or by a set of user IDs), or whose names match a specified filter. User or client access token is required.

Before accessing the methods below, the profileId should be registered as the client own resources the developer console. In this way, the scope access is ensured by the authorization server.

The following operations are supported by the extended profile endpoint:

• CRUD operations on the own user's ExtendedProfile. Profile is identified by profileId (a custom identifier defined by the client). Note that those three values should be intended as the primary key of the profile (no duplicates are allowed). A map String→Object is passed as content and is stored in the ExtendedProfile. Requires user access token.
• Read all the own user extended profiles. Requires user access token.
• Read the profiles shared with the current user (optionally specifying the profileId). Requires user access token.
• Read and search any extended profiles, optionally scoped to a specific profile type. Requires client access token.
• Manipulate (via CRUD operations) a specific profile of a specific user. Requires client access token.

Correspondingly, some of the operations are available with the user access token only (current user profiles, shared profiles), while the other are available only with the client access token (search arbitrary profiles, etc).

The request is emitted to the following endpoint:

https://dev.smartcommunitylab.it/aac/basicprofile

The method allows for accessing the basic profile of the current user.

Permission

profile.basicprofile.me

Request

GET /aac/basicprofile/me HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
    "name": "Mario",
    "surname": "Rossi",
    "socialId": "12345",
    "userId": "6789"
}

The method allows for accessing the account profile of the current user.

Permission

profile.accountprofile.me

Request

GET /aac/accountprofile/me HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
    "accounts": {
        "fbk": {
            "eppn": "rossi@fbk.eu",
            "eu.trentorise.smartcampus.givenname": "Mario",
            "eu.trentorise.smartcampus.surname": "Rossi"
        }
    }
}

The method allows for accessing the account profiles of the specified users.

Permission

profile.accountprofile.all

Parameters

• userIds list of user IDs.

Request

GET /aac/accountprofile/profiles?userIds=1&userIds=2&userIds=3 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
   "profiles": [
     "accounts": {
          "fbk": {
              "eppn": "rossi@fbk.eu",
              "eu.trentorise.smartcampus.givenname": "Mario",
              "eu.trentorise.smartcampus.surname": "Rossi"
          }
      },
      ...
    ]
}          

The method allows for accessing the basic profile of the specified user. The user ID is passed as the path element.

Permission

profile.basicprofile.all

Request

GET /aac/basicprofile/all/{userId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client or user access token}

Response

{
    "name": "Mario",
    "surname": "Rossi",
    "socialId": "12345",
    "userId": "6789"
}

The method allows for accessing the basic profile of the user with the specified social ID. The social ID is passed as the path element.

Permission

profile.basicprofile.all

Request

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

Response

{
    "name": "Mario",
    "surname": "Rossi",
    "socialId": "12345",
    "userId": "6789"
}

The method allows for accessing the basic profiles of the specified users.

Permission

profile.basicprofile.all

Parameters

• userIds list of user IDs.

Request

GET /aac/basicprofile/profiles?userIds=1&userIds=2&userIds=3 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client or user access token}

Response

{
   "profiles": [
      {
         "name": "Mario",
         "surname": "Rossi",
         "socialId": "1",
         "userId": "1"
      },
      {
         "name": "Mario",
         "surname": "Rossi",
         "socialId": "2",
         "userId": "2"
      },
      {
         "name": "Mario",
         "surname": "Rossi",
         "socialId": "3",
         "userId": "3"
      }
    ]
}          

The method allows for accessing the basic profiles of the users whose name/surname matches the specified string (i.e., name/surname contains the string).

Permission

profile.basicprofile.all

Parameters

• filter case-insensitive substring to be searched. If not specified, all users returned.

Request

GET /aac/basicprofile/all?filter=mario HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client or user access token}

Response

{
   "profiles": [
      {
         "name": "Mario",
         "surname": "Rossi",
         "socialId": "1",
         "userId": "1"
      },
      {
         "name": "Mario",
         "surname": "Rossi",
         "socialId": "2",
         "userId": "2"
      },
      {
         "name": "Mario",
         "surname": "Rossi",
         "socialId": "3",
         "userId": "3"
      }
    ]
}          

The requests are emitted to the following endpoint:

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

The method allows for accessing a specific extended profile of the current user.

Permission

extprofile.me.{profileId}.read

Parameters:

• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.

Request

GET /core.profile/extprofile/me/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
    "profileId": "MyProfile",
    "socialId": "12345",
    "userId": "6789",
    "content" : {
        ...
    }
}

The method allows for accessing all extended profiles of the current user.

Permission

extprofile.me.read

Request

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

Response

{
    "content": [
       {
           "profileId": "MyProfile",
           "socialId": "12345",
           "userId": "6789",
           "content" : {
              ...
        }
    ]     
}

The method allows for creating a specific extended profile of the current user. Note that for the user only one instance of the specific profile type may be defined. if the profile of this type already exists, an error is returned.

Permission

extprofile.me.{profileId}.write

Parameters:

• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.
• Request body representing the content of the profile to be created (JSON object).

Request

POST /core.profile/extprofile/me/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
  ....
}

Response: empty

The method allows for update a specific extended profile of the current user. If the profile does not exist, an error will be returned.

Permission

extprofile.me.{profileId}.write

Parameters:

• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.
• Request body representing the content of the profile to be updated (JSON object).

Request

PUT /core.profile/extprofile/me/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
  ....
}

Response: empty

The method allows for deleting a specific extended profile of the current user.

Permission

extprofile.me.{profileId}.write

Parameters:

• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.

Request

DELETE /core.profile/extprofile/me/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response: empty

The method allows for accessing a extended profile of specific type shared with the current user.

Permission

extprofile.shared.{profileId}.read

Parameters:

• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.

Request

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

Response {

  "content": [
     {
         "profileId": "MyProfile",
         "socialId": "12345",
         "userId": "6789",
         "content" : {
            ...
      }
  ]     

} </code>

The method allows for accessing all extended profiles shared with the current user.

Permission

extprofile.shared.read

Request

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

Response

{
    "content": [
       {
           "profileId": "MyProfile",
           "socialId": "12345",
           "userId": "6789",
           "content" : {
              ...
        }
    ]     
}

The method allows for accessing a specific extended profile of the specified user.

Permission

extprofile.write.{profileId}

Parameters:

• userId (path element). User ID.
• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.

Request

GET /core.profile/extprofile/all/{userId}/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
    "profileId": "MyProfile",
    "socialId": "12345",
    "userId": "6789",
    "content" : {
        ...
    }
}

The method allows for creating a specific extended profile of the specified user. Note that for the user only one instance of the specific profile type may be defined. if the profile of this type already exists, an error is returned.

Permission

extprofile.write.{profileId}

Parameters:

• userId (path element). User ID.
• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.
• Request body representing the content of the profile to be created (JSON object).

Request

POST /core.profile/extprofile/app/{userId}/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
  ....
}

Response: empty

The method allows for update a specific extended profile of the specified user. If the profile does not exist, an error will be returned.

Permission

extprofile.write.{profileId}

Parameters:

• userId (path element). User ID.
• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.
• Request body representing the content of the profile to be updated (JSON object).

Request

PUT /core.profile/extprofile/app/{userId}/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
  ....
}

Response: empty

The method allows for deleting a specific extended profile of the specified user.

Permission

extprofile.write.{profileId}

Parameters:

• userId (path element). User ID.
• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.

Request

DELETE /core.profile/extprofile/app/{userId}/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response: empty

The method allows for accessing extended profile that match specified criteria.

Permission

extprofile.all.{profileId}.read

Parameters:

• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.
• Request body representing key→ value pairs (with complex keys) to be matched against the profile content (JSON object).

Request

POST /core.profile/extprofile/all/{profileId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
   "key" : "value",
   "complex.key" : "value"
   ...
}

Response

{
    "content": [
       {
           "profileId": "MyProfile",
           "socialId": "12345",
           "userId": "6789",
           "content" : {
              ...
        }
    ]     
}

The method allows for accessing all extended profiles of the specified users.

Permission

extprofile.all.read

Parameters:

• userIds List of user IDs.

Request

GET /core.profile/extprofile/all?userIds=1&userIds=2&userIds=3 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
    "content": [
       {
           "profileId": "MyProfile",
           "socialId": "12345",
           "userId": "6789",
           "content" : {
              ...
        }
    ]     
}

The method allows for accessing all extended profiles of the specified users scoped to the specified profile type.

Permission

extprofile.all.{profileId}.read

Parameters:

• userIds List of user IDs.
• profileId (path element). Profile type. Should be equivalent to one of the profile type resource parameters defined in the developer console.

Request

GET /core.profile/extprofile/all/{profileId}?userIds=1&userIds=2&userIds=3 HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
    "content": [
       {
           "profileId": "MyProfile",
           "socialId": "12345",
           "userId": "6789",
           "content" : {
              ...
        }
    ]     
}

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

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

To use the library, one has to include the profileservice.client-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 library 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>profileservice.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 two classes, namely BasicProfileService and ExtProfileService. The following code demonstrates how the classes may be used:

BasicProfileService basicProfileService  = new BasicProfileService("https://dev.smartcommunitylab.it/aac");
 
// get token owner profile
BasicProfile profile= basicProfileService.getBasicProfile("token");
System.out.println(profile);
 
// get token owner account profile
AccountProfile accountProfile= basicProfileService.getAccountProfile("token");
System.out.println(accountProfile);
 
// get profiles with filter
List<BasicProfile> results = basicProfileService.getBasicProfiles("a", "token");
System.out.println(results);
 
ExtProfileService extProfileService = new ExtProfileService("https://dev.smartcommunitylab.it/core.profile");
 
// create profile
Map<String, Object> map = new TreeMap<String, Object>();
map.put("keyA", "valueA");
extProfileService.createMyExtendedProfile("myprofile", map, "token");
 
// read profile
ExtendedProfile extProfile = extProfileService.getMyExtendedProfile("myprofile", "token");