Skip to content

SocIoTal Communities Manager

clopez87 edited this page Aug 29, 2016 · 19 revisions

SocIoTal Communities Manager

SocIoTal Communities Manager will provide a standard REST API to create and manage communities within the SocIoTal framework. Through this tool, users will be able to create and manage communities to share selected information with other community members without leaking of information.

Communities SocIoTal

Following, there are described the most important concepts to manage SocIoTal communities:

  • User: represents a user identity within the SocIoTal IdM. Communities Manager provides methods to register, modify and delete a user on the SocIoTal IdM. A user registration is mandatory to create/manage SocIoTal Communities.
  • Domain: represents a collection of communities. By the time, there exists only one domain called SocIoTal. The domain is defined by the “domain name” and the “domain id”. There cannot exist domains with the same name withn the same instance of SocIoTal Platform. New domains can be created (and published) by the SocIoTal Platform administrator.
  • Community: represents a collection of users and entities. The community is defined by the “community name” and the “community id”. There cannot exist communities with the same name within the same domain. Neither can exist users with the same name within the same domain.
  • Role: specifies the role a user assumes within a community and allows them to perform a concrete set of operations. By the time, two roles are used: owner and member. The role “owner” will allow the user to perform all operations within the community (but validate a token). On the other hand, the role “member” will only allow the operations: register a new user, get user info (by ID and name), create a community, request a token (also simple request), list available roles, auto-remove from a community, list communities and list users. New roles (and functionalities) can be defined by the SocIoTal Platform administrator.
  • Community-Token: the Community-Token is an alphanumeric key that will be associated to a specified user (identity) and scoped to a pointed community and domain. This way, the token will identify the requestor user, the community involved, the domain it belongs to and their corresponding role. The requestor user will be able to ask for a token to the Communities Manager by providing the corresponding authentication credentials (user/password) and specifying the selected community (not required if only authentication purposes are needed). If the user is part of that community, a token containing its role within the community (among other info) will be retrieved. Also, it can be request a Community-Token without indicating the community parameter, that token will allow the user to perform concrete actions that does not require to be related to a concrete community but required an authorization token. An end point (the corresponding SocIoTal component) can check, against the Communities Manager, the different token parameters and validate the user through this Community-Token.

The following @IP and PORT will be available for testing purposes:

SocIoTal_CoMM_IP = platform.sociotal.eu

PORT = http --> 3500 https--> 8443

###Register a user

This functionality creates a user and adds it to the SocIoTal IdM (Identity Manager). At the same time, a private community (for this new user purposes) is set up and the role “owner” for this community will be provided. When a user registers a new resource, it will be added by default to their private community and nobody will have access to the private community but the creator (and those who the creator provides access). The users and the private communities will be defined by names and ids. The users will provide the name they want (if it does not exist), and the private community name will correspond with the “userId” value returned in the registration response.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
POST                /SocIoTal_COMM_V1/USERS/addUser
HEADERS             
                    Content-type       application/json

Payload (example)

{
"userName":"Alice",
"nickName":"aliceTest",
"formatted": "Test UC 01 (long)",
"password":"passAlice",
"email": "alice@test.com",
"description":"Alice user description here",
"domainName":"SocIoTal",
"address":{
    "addressType":"Home",
    "addressStreetAddress":"High Street",
    "addressLocality":"Santander",
    "addressPostalCode":"39005",
    "addressCountry":"Spain"
},
"organization":"UC",
"department":"Biology",
"active":true
}

The payload has to include the parameters “name” and “password” (mandatory), but it can also include any of the other parameters. The “active” element sets the user as “enabled” (true) or “disabled” (false). By default, if it is not pointed, the user will be registered as “disabled” (false).

Response (example):

{
  "email": "alice@test.com",
  "domainId": "c43a3df1e0f74480b38158b09ebf0b56",
  "userId": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
  "userName": "Alice",
  "communityId": "73483a29179140909b6e21f86f24a5cd"
}

The response returns a subset of the information provided by the user and the identifiers (Ids) for the domain, user and community. This values have to be kept by the user in order to be used in future actions. The fields “name” and “userId” will be used to identify the user in the rest of calls. The communityId corresponds to the id (not the name) of the private community of the user, which name will have the same value as the userId. Following the example, the name of the private community of Alice will be 88a99ccd-be0a-4db7-af79-d35adcb9650b.

“id” parameter can be also provided (by those applications/developers that already provides a user id) but, by default, the SocIoTal IdM will set the user’s Id.

The “address” parameter MUST be provided with all of its components (shown in the example). If one of them is missing, the whole address element will be ignored.

###Token request (by userName) In order to perform the different actions related to the SocIoTal communities, each user will need the key that give them the correspondent rights and identifies them as member of a given community. This key is the Community-Token that connects the user, with the community and the role the user has within the community.

The user will need a Community-Token for each community that they belong (including their private one). Every token request including a “communityName” will provide a token valid (if the user belongs to the community and it is properly authenticated) ONLY for the community pointed. A “communityName” is unique ONLY for a given domain, pointed here by the “domainName” element. If the user belongs to several communities, a different token, for each community should be requested. If no “communityName” is provided, the Community-Token retrieved will only authenticates the user and won’t be valid to access any community.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
POST                /SocIoTal_COMM_V1/TOKEN/request
HEADERS             
                    Content-type       application/json

Above is presented an example to request a token for the private community of the user. The “communityName”, which represents the name of the private community of the user, corresponds with the UserId (obtained from the response of the registering request).

Payload (example):

{
"userName":"Alice",
"password":"passAlice",
"domainName":"SocIoTal",
"communityName":"88a99ccd-be0a-4db7-af79-d35adcb9650b"  //USER_ID
}

Response (example):

{
  "values": {
    "token": {
      "methods": [
        "password"
      ],
      "issued_at": "2016-03-09T16:43:49.532976Z",
      "expires_at": "2016-03-23T16:43:49.532947Z",
      "audit_ids": [
        "PhYbsJmjRlyzi7XVrF1xRA"
      ],
      "roles": [
        {
          "id": "ff0422fda2cf4c0c89e5b9260ec79a45",
          "name": "owner"
        }
      ],
      "community": {
        "id": "73483a29179140909b6e21f86f24a5cd",
        "name": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
        "domain": {
          "id": "c43a3df1e0f74480b38158b09ebf0b56",
          "name": "SocIoTal"
        }
      },
      "user": {
        "id": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
        "name": "Alice",
        "domain": {
          "id": "c43a3df1e0f74480b38158b09ebf0b56",
          "name": "SocIoTal"
        }
      }
    }
  },
  "communityToken": "ec9c720050374b7d99be350974164d70"
}

The response is a json with two main fields: the token information and the community token itself. At the example it can be identified the method with which the token has been requested (user’s password). Also it is provided the date when the token has been requested (“issued_at”) and when it will expired (“expires_at”). Also it is provided information about the user (“id”, “name” and “domain”), the community (“id”, “name” and “domain”), and the role the user plays within the community (“id” and “name”).

###Request a token (by userID) This call allows to obtain a token by using the userID instead of the userName as the case presented before.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
POST                /SocIoTal_COMM_V1/TOKEN/request
HEADERS             
                    Content-type       application/json

Payload (example):


{
"id":"88a99ccd-be0a-4db7-af79-d35adcb9650b",
"password":"passAlice",
"domainName":"SocIoTal",
"communityName":"88a99ccd-be0a-4db7-af79-d35adcb9650b"
}

Response (example):

{
  "values": {
    "token": {
      "methods": [
        "password"
      ],
      "issued_at": "2016-03-09T16:44:57.449926Z",
      "expires_at": "2016-03-23T16:44:57.449895Z",
      "audit_ids": [
        "cCusvDeNSLmm8xFViKW3qw"
      ],
      "roles": [
        {
          "id": "ff0422fda2cf4c0c89e5b9260ec79a45",
          "name": "owner"
        }
      ],
      "community": {
        "id": "73483a29179140909b6e21f86f24a5cd",
        "name": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
        "domain": {
          "id": "c43a3df1e0f74480b38158b09ebf0b56",
          "name": "SocIoTal"
        }
      },
      "user": {
        "id": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
        "name": "Alice",
        "domain": {
          "id": "c43a3df1e0f74480b38158b09ebf0b56",
          "name": "SocIoTal"
        }
      }
    }
  },
  "communityToken": "1f9a7a27bac7462f83c2684d025da1ff"
}

The response is a json with two main fields: the token information and the community token itself. At the example it can be identified the method with which the token has been requested (user’s password). Also it is provided the date when the token has been requested (“issued_at”) and when it will expired (“expires_at”). Also it is provided information about the user (“id”, “name” and “domain”), the community (“id”, “name” and “domain”), and the role the user plays within the community (“id” and “name”).

###Request a token (by tokenUUID) This call allows to obtain a token by using the tokenUUID. The response will provide a new token that will not extend the duration of the token provided in the request, but it will expand the scope of the token. This means that with this method it can be obtained a token which is valid for more than one community.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
POST                /SocIoTal_COMM_V1/TOKEN/request
HEADERS             
                    Content-type       application/json

Payload (example):

{
"tokenUUID":"1f9a7a27bac7462f83c2684d025da1ff",
"domainName":"SocIoTal",
"communityName":"88a99ccd-be0a-4db7-af79-d35adcb9650b"
}

###Simple token request (by userName)

This call is a short version of the calls presented before and it has been designed for devices that wants to avoid processing the response. The required payload is the same than the call presented before, but the response will return only the “Community-Token” as plain text.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
POST                /SocIoTal_COMM_V1/TOKEN/simpleRequest
HEADERS             
                    Content-type       application/json

Above is presented an example to request a token for the private community of the user. The “name” field corresponds with the “nickname” of the user during the registration or, which amounts to the same, the “name” returned in the registering response. The “communityName”, which represents the name of the private community of the user, corresponds with the UserId (obtained from the response of the registering request).

Payload (example):

{
"userName":"Alice",
"password":"passAlice",
"domainName":"SocIoTal",
"communityName": "88a99ccd-be0a-4db7-af79-d35adcb9650b"
}

Response (example):

fb375df37c1147f8aa0681fe0ecd0640

###Simple token request (by userId) This call allows to obtain a simple token (only the “Community-Token” as plain text) by using the userID instead of the userName as the case presented before.

Payload (example):

{
"id":"88a99ccd-be0a-4db7-af79-d35adcb9650b",
"password":"passAlice",
"communityName": "88a99ccd-be0a-4db7-af79-d35adcb9650b"
}

Response (example):

e515bb7ba9724270bec11a8b68de0fbf

###Validate a token

This functionality returns the information of the token provided as part of the URL. This action is performed by those architectural components that needs to validate if a user has the proper right to perform an action. The components will check and get the given Community-Token information (perform the validation of a token) whenever a user wants to perform and action in the architecture. The “Community-Token” parameter represents the UUID of the token (what we call Community-Token itself e.g. e515bb7ba9724270bec11a8b68de0fbf) and, in order to perform this call, the platform admin-token is required. This method is restricted to the SocIoTal Components that need to validate a Community-Token. In future releases, a special token for “apps” and developers will be included in order this Community-Token can be used by other components/apps outside of SocIoTal Integrated Platform.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
GET                 /SocIoTal_COMM_V1/TOKEN/validate/community-token
HEADERS             
                    Content-type       application/json
                    Community-Token    admin-token 

Payload (example):

No payload

Response (example using Alice private Community-Token):

{
  "token": {
    "methods": [
      "password"
    ],
    "issued_at": "2016-03-09T16:48:21.573100Z",
    "expires_at": "2016-03-23T16:48:21.573071Z",
    "audit_ids": [
      "F9VqedQJRMOvybXIOKD7bg"
    ],
    "roles": [
      {
        "id": "ff0422fda2cf4c0c89e5b9260ec79a45",
        "name": "owner"
      }
    ],
    "community": {
      "id": "73483a29179140909b6e21f86f24a5cd",
      "name": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
      "domain": {
        "id": "c43a3df1e0f74480b38158b09ebf0b56",
        "name": "SocIoTal"
      }
    },
    "user": {
      "id": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
      "name": "Alice",
      "domain": {
        "id": "c43a3df1e0f74480b38158b09ebf0b56",
        "name": "SocIoTal"
      }
    },
    "extras": {}
  }
}

The response is a json which provides information related with the Community-Token. At the example it can be identified the method with which the token has been requested (the user password). Also it is indicated the date when the token was requested (“issued_at”) and when it will expired (“expires_at”). Also it is provided information about the user (“id”, “name” and “domain”), the community which is called “project” (“id”, “name” and “domain”), and the role the user plays within the community (“id” and “name”).

###Get user info by ID

This functionality will allow the requester to get information about a user by providing their User-id. Only users from the same community can get information about other users. The community will be pointed by the Community-Token provided in the request, so they will use the Community-Token of the same community they are requesting info.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
GET                 /SocIoTal_COMM_V1/USERS/getUserInfobyID/userID
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

For the following example the user provides the Community-Token of her own private community, so she will receive information about himself.

Payload (example):

No Body 

Response (example using the userID from Alice 88a99ccd-be0a-4db7-af79-d35adcb9650b and her private Community-Token e515bb7ba9724270bec11a8b68de0fbf):

{
  "user": {
    "formatted": "Test UC 01 (long)",
    "enabled": true,
    "department": "Biology",
    "addressStreetAddress": "High Street",
    "domain_id": "c43a3df1e0f74480b38158b09ebf0b56",
    "addressType": "Home",
    "userCommunityId": "73483a29179140909b6e21f86f24a5cd",
    "id": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
    "organization": "UC",
    "username": null,
    "addressLocality": "Santander",
    "attName": {
      "formatted": "Test UC 01 (long)"
    },
    "email": "alice@test.com",
    "nickName": "aliceTest",
    "description": "Alice user description here",
    "name": "Alice",
    "userName": "Alice",
    "addressPostalCode": "39005",
    "addressCountry": "Spain",
    "addresses": [
      {
        "streetAddress": "High Street",
        "postalCode": "39005",
        "locality": "Santander",
        "type": "Home",
        "country": "Spain"
      }
    ]
  }
}

The response provides information about the user among which you can find the the userID, the userName, the domain and the ID of the private community of the user.

###Get user info by name

This functionality will allow the requester to get information about a user by providing the user name. Only users from the same community can get information about other users. The community will be pointed by the Community-Token provided in the request, so they will use the Community-Token of the same community they’re requesting info. The user nick name will be added at the end of the URL.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
GET                 /SocIoTal_COMM_V1/USERS/getUserInfobyName/UserNickName
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

For the following example the user provides the Community-Token of her private community, so she will receive information about herself.

Payload (example using Alice's userNAme and her private Community-Token e515bb7ba9724270bec11a8b68de0fbf):

userName = Alice
Community-Token = e515bb7ba9724270bec11a8b68de0fbf

Response (example):

{
  "users": [
    {
      "formatted": "Test UC 01 (long)",
      "enabled": true,
      "department": "Biology",
      "addressStreetAddress": "High Street",
      "domain_id": "c43a3df1e0f74480b38158b09ebf0b56",
      "addressType": "Home",
      "userCommunityId": "73483a29179140909b6e21f86f24a5cd",
      "id": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
      "organization": "UC",
      "username": null,
      "addressLocality": "Santander",
      "attName": {
        "formatted": "Test UC 01 (long)"
      },
      "email": "alice@test.com",
      "nickName": "aliceTest",
      "description": "Alice user description here",
      "name": "Alice",
      "userName": "Alice",
      "addressPostalCode": "39005",
      "addressCountry": "Spain",
      "addresses": [
        {
          "streetAddress": "High Street",
          "postalCode": "39005",
          "locality": "Santander",
          "type": "Home",
          "country": "Spain"
        }
      ]
    }
  ]
}

The response provides information about the user among which you can find the the userID, the userName, the domain and the ID of the private community of the user.

###Create a community

Creates a community and assigns the “owner” role to the user which has request the petition. The tool will extract the information about who has made the request from the Community-Token attached in the headers. The required Community-Token should be only linked to the same domain the new community wants to be created. No community scoped nor specific role are required. In the example, Alice creates a new community called "AliceNeighborhoud" and she uses one of her tokens to be able to make the request (e.g. e515bb7ba9724270bec11a8b68de0fbf).

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
POST                /SocIoTal_COMM_V1/COMMUNITIES/create
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

Payload (example):

{
"description":"Alice neighborhoud",
"communityName": "AliceNeighborhoud",
"contact":{
   "email01":"alice@test.com"
   },
"extraData":{
   "extradesc":"Extra description of Alice neighborhoud"
   }
}

Within the payload only a description and a communityName (up to the creator) have to be provided. Further info could be provided to describe/complement the community in further versions.

Response (example):

{
  "community": {
    "id": "fd0949c52a9042fe839e665898f98080",
    "name": "AliceNeighborhoud"
  },
  "domain": {
    "id": "c43a3df1e0f74480b38158b09ebf0b56",
    "name": "SocIoTal"
  },
  "owner": {
    "id": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
    "name": "Alice"
  }
}

Within the response, information (“id” and “name”) about the new community, the domain and the owner is provided. The response will be an array with items that identify the communities which the user belongs to, providing the communityId and the roleId of the user within the community.

###List communities

Provides a list of the communities of a domain (by default the SocIoTal domain). The user will be identified only with a Community-Token provided by the platform (it doesn’t need to be related to a concrete community). In the example Alice request the list of communities usint the Community-Token e515bb7ba9724270bec11a8b68de0fbf.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
GET                 /SocIoTal_COMM_V1/COMMUNITIES/list
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

Payload (example):

No Body

Response (example):

{
  "Communities": [
    {
      "id": "4c9319426da94c1f8267e2ae2e22f619",
      "enabled": true,
      "description": "Private Community of [Test02_00=>337091ff-af3a-45cb-9ad2-de0ebf6c637b]",
      "name": "337091ff-af3a-45cb-9ad2-de0ebf6c637b"
    },
    {
      "id": "73483a29179140909b6e21f86f24a5cd",
      "enabled": true,
      "description": "Private Community of [Alice=>88a99ccd-be0a-4db7-af79-d35adcb9650b]",
      "name": "88a99ccd-be0a-4db7-af79-d35adcb9650b"
    },
    {
      "id": "3205ebdbd33b4e2b9d73531655ce1185",
      "enabled": true,
      "description": "Private Community of [Maria=>9c965137-61a9-4561-88b8-b3e1f448a3b9]",
      "name": "9c965137-61a9-4561-88b8-b3e1f448a3b9"
    },
    {
      "id": "fd0949c52a9042fe839e665898f98080",
      "enabled": true,
      "description": "Alice neighborhoud",
      "name": "AliceNeighborhoud"
    }
    
  ],
  "domain": "SocIoTal",
  "domain_id": "c43a3df1e0f74480b38158b09ebf0b56"
}

The response provides a list of the available communities in the domain. It is provided the id, description and name of each community, with the domain and domain_id.

###Get Community Info This function allows to obtain further information about a concrete community by the community Name or the community ID. Within the body it will be defined the community name or the communityID, and within the headers there will be included a Community-Token from a community within the same domain of the requested community.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
POST                /SocIoTal_COMM_V1/COMMUNITIES/getCommunity
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

Payload (example):

{
    "communityID" : "fd0949c52a9042fe839e665898f98080"
}

Response (example):

{
  "Community": {
    "id": "fd0949c52a9042fe839e665898f98080",
    "enabled": true,
    "description": "Alice neighborhoud",
    "name": "AliceNeighborhoud",
    "domain_id": "c43a3df1e0f74480b38158b09ebf0b56",
    "owner": {
      "id": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
      "userName": "Alice"
    },
    "extraData": {
      "extradesc": "Extra description of Alice neighborhoud"
    },
    "contact": {
      "email01": "alice@test.com"
    }
  }
}

###List available roles

List a set of roles to be applied to users when adding them to a community. The user will be identified only with a Community-Token provided by the platform (it doesn’t need to be related to a concrete community). In the following example, Alice request a list of the available roles and she uses the Community-Token e515bb7ba9724270bec11a8b68de0fbf.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
GET                 /SocIoTal_COMM_V1/COMMUNITIES/listRoles
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

Payload (example):

No payload

Response (example):

{
  "roles": [
    {
      "id": "b250ea5c0e364aa289eff45b7d0ac36c",
      "name": "member"
    },
    {
      "id": "ff0422fda2cf4c0c89e5b9260ec79a45",
      "name": "owner"
    },
    {
      "id": "5f33a94c4e2b4056bfb7f4079a2e7068",
      "name": "trial",
      "is_default": true
    },
    {
      "id": "170f266eb22849acb4a8544484683696",
      "name": "basic",
      "is_default": true
    },
    {
      "id": "02a89fc3e8154228ac7740b63520081e",
      "name": "community",
      "is_default": true
    },
    {
      "id": "5f90f828f9b7454ea1460c09740aedff",
      "name": "admin",
      "is_default": true
    }
  ]

Currently, only “member” and “owner” roles are being interpreted by the SocIoTal platform, the rest will received a response of “Unauthorized”.

###Assign a role

This functionality adds a user to a community by assigning them the role to play within the community. Only an owner of the community is able to add a user to the community, and they will use their Community-Token of the community as a header of the request. For the example, it has been created a new user Bob with results to have the "userId=e697d4ff-6132-4397-ac6c-6705a26bcdcf". Alice want to add him to the "AliceNeighborhoud" community assigning him the role "member". In order to do that, Alice has previously requested a Community-Token to manage her "AliceNeighborhoud" community (81d3db6e59c34884a72f72b297550f27).

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
PUT                 /SocIoTal_COMM_V1/COMMUNITIES/assignRole
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

Payload (example):

{
    "userId":"f5a921af-3b1a-4d32-b2bf-ba0fff59bb04",
    "roleId":"b250ea5c0e364aa289eff45b7d0ac36c"
}

The “userId” will correspond with the Id of the user to be added. The “roleId” will correspond with the Id of the role (owner or member).

Instead of the “roleId” it can be used the “roleName”, also instead of “userId” it can be used the user Nick-Name.

Response (example):

{
  "community": {
    "id": "fd0949c52a9042fe839e665898f98080",
    "name": "AliceNeighborhoud"
  },
  "domain": {
    "id": "c43a3df1e0f74480b38158b09ebf0b56",
    "name": "SocIoTal"
  },
  "role": {
    "id": "b250ea5c0e364aa289eff45b7d0ac36c",
    "name": "member"
  },
  "user": {
    "id": "f5a921af-3b1a-4d32-b2bf-ba0fff59bb04",
    "name": "Bob"
  }
}

The response provides information about the community, the domain, the added user and its role.

###List users

Lists users within a community and their corresponding roles. The community will be specified by the Community-Token heading the request, since this operation only can be done by a user belonging to the community. For the example, also have been added other new user (apart from Bob) called Charlie. Charlie has also been added with the member role. The Community-Token that Alice have used to make the request is the one for the community "AliceNeighborhoud" (81d3db6e59c34884a72f72b297550f27).

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
GET                 /SocIoTal_COMM_V1/COMMUNITIES/listUsers
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

Payload (example):

No payload

Response (example):

{
  "Users": [
    {
      "role": {
        "id": "b250ea5c0e364aa289eff45b7d0ac36c",
        "name": "member"
      },
      "user": {
        "id": "17f75ea9-394b-486d-b606-bb7fe25f0b00",
        "name": "Charlie"
      }
    },
    {
      "role": {
        "id": "ff0422fda2cf4c0c89e5b9260ec79a45",
        "name": "owner"
      },
      "user": {
        "id": "88a99ccd-be0a-4db7-af79-d35adcb9650b",
        "name": "Alice"
      }
    },
    {
      "role": {
        "id": "b250ea5c0e364aa289eff45b7d0ac36c",
        "name": "member"
      },
      "user": {
        "id": "f5a921af-3b1a-4d32-b2bf-ba0fff59bb04",
        "name": "Bob"
      }
    }
  ],
  "community": {
    "id": "fd0949c52a9042fe839e665898f98080",
    "name": "AliceNeighborhoud",
    "domain": "SocIoTal"
  }
}

The response is a json containing an array of objects presenting the users (“id” and “name”) and their corresponding roles (“id” and “name”). Also, information about the community (“id”, “name” and “domain”) is returned.

###Revoke a role

Removes a user from a community. This is an action that can be only performed by the owner of the community (a role “owner” belonging to the referenced community is required), so the Community-Token for the heading will be the one from the owner (or an owner) of the community. In the following example, Alice want to remove Charlie (with the userId=17f75ea9-394b-486d-b606-bb7fe25f0b00) from the "AliceNeighborhoud". Alice will need the Community-Token to manage the "AliceNeighborhoud" community (81d3db6e59c34884a72f72b297550f27).

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
DELETE              /SocIoTal_COMM_V1/COMMUNITIES/revokeRole
HEADERS             
                    Content-type       application/json
                    Community-Token    community_token

Payload (example):

{
    "userId":"17f75ea9-394b-486d-b606-bb7fe25f0b00",
    "role":"member"
}

The “userId” and the role will correspond to the userId and the role of the user to be removed from the community.

Response (example):

204 No Content

###autoRemove from a community

The revoke role function allows the owner of a community to remove a user from the community, but if users want to remove themselves from a community they will be able to autoremove themselves from the community through this function. You must have in mind that if the user to be removed is the owner of the community, the community will remain without an owner, so most of the actions will not be performed by other users (unless the community had more than one owner). The request doesn’t require a body and the user and the community is obtained by the Community-Token of the user within the correspondent community. In the following example Bob wants to remove himself from the "AliceNeighborhoud" community. In order to do that he has requested before a Community-Token to access the community (43e9a41590df475795c98ff3ba3e7e4c)

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
DELETE              /SocIoTal_COMM_V1/COMMUNITIES/autoRemove
HEADERS             
                    Content-type       application/json
                    Community-Token    community_token

Payload (example):

No payload

Response (example):

204 No Content

###Delete a user

This functionality deletes a user from the User Directory plus their private community. Only the correspondent user can remove itself. You must have in mind that if the user to be deleted is the owner of other communities, they will remain without an owner, so most of the actions will not be performed by other users (unless the community had more than one owner). For the example, Charlie wants to remove his user (with the userId=17f75ea9-394b-486d-b606-bb7fe25f0b00) from the platform. For that, he first request the token for his private community (77dd34cc959f4c2982d091ddcfab774d) to be added to the header of the request.

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
DELETE                 /SocIoTal_COMM_V1/USERS/deleteUser/userID
HEADERS             
                    Content-type       application/json
                    Community-Token    private_community_token

Payload (example):

No payload
http://193.144.201.50:3500/SocIoTal_COMM_V1/USERS/deleteUser/17f75ea9-394b-486d-b606-bb7fe25f0b00

Response (example):

204 No content

###Delete a community

This functionality deletes a community. Only an owner of the community is able to delete de community. The community to be deleted is pointed by adding the communityId to the URL. In the example, Alice is going to remove the "AliceNeighborhoud" community, and she needs her Community-Token for "AliceNeighborhoud".

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
DELETE              /SocIoTal_COMM_V1/COMMUNITIES/deleteCommunity/communityId
HEADERS             
                    Content-type       application/json
                    Community-Token    community_token

Payload (example):

No payload

Response (example):

204 No Content

###List my communities

List the communities to which the users belongs to. The user will be identified by one of its Community-Token. In the following example, Alice want to list her communities (the result must be her private one, because she had removed the one she created).

SocIoTal SERVER     SocIoTal_CoMM_IP:PORT  
GET                 /SocIoTal_COMM_V1/COMMUNITIES/listMyCommunities
HEADERS             
                    Content-type       application/json
                    Community-Token    community-token

Payload (example):

No body

Response (example):

{
  "communities": [
    {
      "roleId": "ff0422fda2cf4c0c89e5b9260ec79a45",
      "communityId": "73483a29179140909b6e21f86f24a5cd"
    }
  ]
}
You can’t perform that action at this time.