9.4.3.1.4. Space and space membership

Here is a Space JSON returned by GET /v1/social/spaces/{space_id}:

{
  "id": "1d911fee7f00010116754edd66d77e6c",
  "href": "http://localhost:8080/rest/v1/social/spaces/1d911fee7f00010116754edd66d77e6c",
  "identity": "http://localhost:8080/rest/v1/social/identities/1d9120607f00010103ee7cad5d1ce1ce",
  "groupId": "/spaces/documentation",
  "applications": [
    {
      "id": "ForumPortlet",
      "displayName": "Forums"
    },
    {
      "id": "WikiPortlet",
      "displayName": "wiki"
    },
    {
      "id": "FileExplorerPortlet",
      "displayName": "Documents"
    },
    {
      "id": "CalendarPortlet",
      "displayName": "Agenda"
    },
    {
      "id": "SpaceSettingPortlet",
      "displayName": "Space Settings"
    },
    {
      "id": "MembersPortlet",
      "displayName": "Members"
    }
  ],
  "managers": "http://localhost:8080/rest/v1/social/spaces/1d911fee7f00010116754edd66d77e6c/users?role=manager",
  "members": "http://localhost:8080/rest/v1/social/spaces/1d911fee7f00010116754edd66d77e6c/users",
  "displayName": "development",
  "description": "abc",
  "url": null,
  "avatarUrl": "/rest/jcr/repository/social/production/soc%3Aproviders/soc%3Aspace/soc%3Adocumentation/soc%3Aprofile/soc%3Aavatar/?upd=1443606140698",
  "visibility": "private",
  "subscription": "open"
}

In Create and Update, you can use an effective version that contains several fields. See the following examples.

Create a space:

POST /v1/social/spaces
{
	"displayName":"tomato",
	"description":"vegetable",
	"visibility":"private",
	"subscription":"open"
}

Update a space by its Id:

PUT /v1/social/spaces/{space_id}
{
	"displayName":"tomato",
	"description":"vegetable",
	"visibility":"hidden",
	"subscription":"validation"
}

Delete a space by its Id:
```
DELETE /v1/social/spaces/{space_id}
```

Visibility can be private or hidden. Subscription can be open, validation or close.

To get users of a space:

GET /v1/social/spaces/{space_id}/users

To get only the manager, append a query param role=manager:

GET /v1/social/spaces/{space_id}/users?role=manager

Space Membership

A membership can be a "member" or a "manager" role (A manager has both memberships).

{
  "id": "documentation:john:member",
  "href": "http://localhost:8080/rest/v1/social/spacesMemberships/documentation:john:member",
  "user": "http://localhost:8080/rest/v1/social/users/john",
  "space": "http://localhost:8080/rest/v1/social/spaces/1d911fee7f00010116754edd66d77e6c",
  "role": "member",
  "status": "approved"
}

The endpoint to work with space membership is /v1/social/spacesMemberships. The following examples show the abilities of this service:

Get memberships of a space, using query param space={space_display_name}:
```
GET /v1/social/spacesMemberships?space=documentation
```
Get memberships of a user, using query param user={username}:
```
GET /v1/social/spacesMemberships?user=john
```
Get memberships filtered by status (all/pending/approved), using query param status={status}:
```
GET /v1/social/spacesMemberships?space=documentation&status=pending
```
Delete a membership by its Id. The membership Id is formed by space display name and username and role.
```
DELETE /v1/social/spacesMemberships/space1:user1:member
```

In Create, an effective version of the JSON entity can be used. Notice username and space display name are used.

Create membership:

POST /v1/social/spacesMemberships
{
	"user":"user1",
	"space":"space1"
}

The use is limited to two cases: a space manager adds a user to the space, or a user joins an open space. In the second one, the space (subscription) must be "open" and the "user" (JSON) field must be set to the authenticated user. In the both cases, the status of created membership is always "approved".

For the same logic, it does not make sense to update a space membership though Update method is available.