Members

Community members¶

The members API allows you to manage members of a community.

Read vs. write separation

The members REST API separates writes from reads. This means all state changing requests (POST, PUT or DELETE) does not return any results (i.e. 204 HTTP response code). You must issue a GET request to retrieve the updated object. Changes are applied asynchronously so you may get outdated information if you query right after an update. Changes are normally applied within seconds.

The following general restrictions apply to the member API:

Owners can manage all roles including owners (except themselves).
Managers can manage all roles except owners (except themselves).
A community MUST always have at least one owner.
User can leave a community.
Members can change their own visibility to both public/hidden.
Owners/managers can change visibility of members to hidden.

Get Community Members¶

GET /api/communities/{id}/members

Parameters

Name	Type	Location	Description
`id`	string	path	Community UUID identifier or slug e.g. `bd647379-23ea-477a-970f-201512ae5624` or `my-super-community`
`accept`	string	header	- `application/json`
`q`	string	query	Search query used to filter results.
`sort`	string	query	Sort search results. Customizable. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (default: `"bestmatch"` or `"name"`).
`size`	integer	query	Specify number of items in the results page (default: 10).
`page`	integer	query	Specify the page of results.
`role`	string	query	Filter by role (one of `reader`, `curator`, `manager`, `owner`).
`visibility`	boolean	query	Filter by visibility (one of `true`, `false`)

Sort options for community members can be configured using the COMMUNITIES_MEMBERS_SORT_OPTIONS config variable as described in the search customization section. Note that "bestmatch" is only available as a sort option on requests that provide a query string as a q parameter, in which case it is the default sort type. If no query string is provided in the request, the default sort type is "name". In this case a "bestmatch" value is ignored and the default "name" sort is used.

Request

GET /api/communities/{id}/members HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "hits": {
        "hits": [
            {
                "member": {
                    "type": "user",
                    "id": "4",
                    "name": "Jose Benito Gonzalez Lopez",
                    "description": "CERN",
                    "avatar": "https://127.0.0.1:5000/api/users/4/avatar.svg"
                },
                "id": "4730bf2b-f440-454f-b205-d79842ea809f",
                "updated": "2022-05-23T15:18:11.969226+00:00",
                "permissions": {
                    "can_leave": false,
                    "can_delete": true,
                    "can_update_role": true,
                    "can_update_visible": false
                },
                "role": "reader",
                "created": "2022-05-23T15:17:14.618960+00:00",
                "revision_id": 3,
                "visible": false,
                "is_current_user": false
            },
            {
                "member": {
                    "type": "user",
                    "id": "3",
                    "name": "Lars Holm Nielsen",
                    "description": "CERN",
                    "avatar": "https://127.0.0.1:5000/api/users/3/avatar.svg"
                },
                "id": "3e78d5d1-c162-46b4-8f3c-da2edc8f1192",
                "updated": "2022-05-23T12:42:08.763029+00:00",
                "permissions": {
                    "can_leave": true,
                    "can_delete": false,
                    "can_update_role": false,
                    "can_update_visible": true
                },
                "role": "owner",
                "created": "2022-05-23T12:06:20.437809+00:00",
                "revision_id": 3,
                "visible": true,
                "is_current_user": true
            }
        ],
        "total": 2
    },
    "aggregations": {
        "role": {
            "buckets": [
                {
                    "key": "owner",
                    "doc_count": 1,
                    "label": "Owner",
                    "is_selected": false
                },
                {
                    "key": "reader",
                    "doc_count": 1,
                    "label": "Reader",
                    "is_selected": false
                }
            ],
            "label": "Role"
        },
        "visibility": {
            "buckets": [
                {
                    "key": "false",
                    "doc_count": 1,
                    "label": "Hidden",
                    "is_selected": false
                },
                {
                    "key": "true",
                    "doc_count": 1,
                    "label": "Public",
                    "is_selected": false
                }
            ],
            "label": "Visibility"
        }
    },
    "sortBy": "name",
    "links": {
        "self": "https://127.0.0.1:5000/api/communities/bd647379-23ea-477a-970f-201512ae5624/members?page=1&q=&size=25&sort=name"
    }
}

Search public members¶

GET /api/communities/{id}/members/public

Parameters

Name	Type	Location	Description
`id`	string	path	Community UUID identifier or slug e.g. `bd647379-23ea-477a-970f-201512ae5624` or `my-super-community`
`accept`	string	header	- `application/json`
`q`	string	query	Search query used to filter results.
`size`	integer	query	Specify number of items in the results page (default: 10).
`page`	integer	query	Specify the page of results.

Note that no sort options are available when searching public members. The results are sorted by "name" in ascending order.

Request

GET /api/communities/bd647379-23ea-477a-970f-201512ae5624/members/public HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "hits": {
        "hits": [
            {
                "member": {
                    "type": "user",
                    "id": "3",
                    "name": "Lars Holm Nielsen",
                    "description": "CERN",
                    "avatar": "https://127.0.0.1:5000/api/users/3/avatar.svg"
                },
                "id": "3e78d5d1-c162-46b4-8f3c-da2edc8f1192"
            }
        ],
        "total": 1
    },
    "sortBy": "name",
    "links": {
        "self": "https://127.0.0.1:5000/api/communities/bd647379-23ea-477a-970f-201512ae5624/members?page=1&q=&size=25&sort=name"
    }
}

Search invitations¶

GET /api/communities/{id}/invitations

Parameters

Name	Type	Location	Description
`id`	string	path	Community UUID identifier or slug e.g. `bd647379-23ea-477a-970f-201512ae5624` or `my-super-community`
`accept`	string	header	- `application/json`
`q`	string	query	Search query used to filter results.
`sort`	string	query	Sort search results. Customizable. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (default: `"bestmatch"` or `"name"`).
`size`	integer	query	Specify number of items in the results page (default: 10).
`page`	integer	query	Specify the page of results.
`role`	string	query	Filter by role (one of `reader`, `curator`, `manager`, `owner`).
`status`	string	query	Filter by status (one of `submitted`, `accepted`, `declined`, `expired`, `cancelled`)
`is_open`	boolean	query	Filter by open/closed (one of `true`, `false`)

Sort options for community members can be configured using the COMMUNITIES_INVITATIONS_SORT_OPTIONS config variable as described in the search customization section. Note that "bestmatch" is only available as a sort option on requests that provide a query string as a q parameter, in which case it is the default sort type. If no query string is provided in the request, the default sort type is "name". In this case a "bestmatch" value is ignored and the default "name" sort is used.

Request

GET /api/communities/bd647379-23ea-477a-970f-201512ae5624/invitations HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "hits": {
        "hits": [
            {
                "member": {
                    "type": "user",
                    "id": "4",
                    "name": "Jose Benito Gonzalez Lopez",
                    "description": "CERN",
                    "avatar": "https://127.0.0.1:5000/api/users/4/avatar.svg"
                },
                "id": "252df09b-8fab-4818-8553-a5bf09abfab3",
                "updated": "2022-05-23T12:41:40.779087+00:00",
                "permissions": {
                    "can_cancel": false,
                    "can_update_role": false
                },
                "request": {
                    "is_open": false,
                    "id": "c4381dc0-a395-4291-b4cf-5164f01f1778",
                    "expires_at": "2022-06-22T12:41:19.353850",
                    "status": "accepted"
                },
                "role": "reader",
                "created": "2022-05-23T12:41:19.403553+00:00",
                "revision_id": 1,
                "visible": false,
                "is_current_user": false
            },
            {
                "member": {
                    "type": "user",
                    "id": "4",
                    "name": "Jose Benito Gonzalez Lopez",
                    "description": "CERN",
                    "avatar": "https://127.0.0.1:5000/api/users/4/avatar.svg"
                },
                "id": "4730bf2b-f440-454f-b205-d79842ea809f",
                "updated": "2022-05-23T15:18:11.973365+00:00",
                "permissions": {
                    "can_cancel": false,
                    "can_update_role": false
                },
                "request": {
                    "is_open": false,
                    "id": "9033a8d5-6fa2-4685-87c7-e20c527535d8",
                    "expires_at": "2022-06-22T15:17:14.550679",
                    "status": "accepted"
                },
                "role": "reader",
                "created": "2022-05-23T15:17:14.618960+00:00",
                "revision_id": 1,
                "visible": false,
                "is_current_user": false
            }
        ],
        "total": 2
    },
    "aggregations": {
        "role": {
            "buckets": [
                {
                    "key": "reader",
                    "doc_count": 2,
                    "label": "Reader",
                    "is_selected": false
                }
            ],
            "label": "Role"
        },
        "status": {
            "buckets": [
                {
                    "key": "accepted",
                    "doc_count": 2,
                    "label": "Accepted",
                    "is_selected": false
                }
            ],
            "label": "Status"
        },
        "is_open": {
            "buckets": [
                {
                    "key": "false",
                    "doc_count": 2,
                    "label": "Closed",
                    "is_selected": true
                }
            ],
            "label": "Status"
        }
    },
    "sortBy": "name",
    "links": {
        "self": "https://127.0.0.1:5000/api/communities/bd647379-23ea-477a-970f-201512ae5624/members?is_open=false&page=1&q=&size=10&sort=name"
    }
}

Add group members¶

POST /api/communities/{id}/members

Note, only groups can be added directly as member of a community. Users must be invited.

The Python programmatic API supports adding users without inviting them via the system identity.

Parameters

Name	Type	Location	Description
`id`	string	path	Community UUID identifier or slug e.g. `bd647379-23ea-477a-970f-201512ae5624` or `my-super-community`
`content-type`	string	header	- `application/json`
`members`	object	body	List of group members to add.
`role`	string	body	Set role of group (one of `reader`, `curator`, `manager`, `owner`).
`visible`	boolean	body	Set visibility (one of `true`, `false`)

Request

POST /api/communities/acc9058e-b034-49d0-a008-af971a69c34d/members HTTP/1.1
Content-Type: application/json

{
    "members": [
        {
            "id": "admin",
            "type": "group"
        }
    ],
    "role": "curator"
}

Response

HTTP/1.1 204 NO CONTENT

Invite user members¶

POST /api/communities/{id}/invitations

Note, only users can be invited. Groups must be added directly.

Parameters

Name	Type	Location	Description
`id`	string	path	Community UUID identifier or slug e.g. `bd647379-23ea-477a-970f-201512ae5624` or `my-super-community`
`content-type`	string	header	- `application/json`
`members`	object	body	List of group members to add.
`role`	string	body	Set role of group (one of `reader`, `curator`, `manager`, `owner`).
`visible`	boolean	body	Set visibility (one of `true`, `false`)
`message`	string	body	A message to the user being invited.

Request

POST /api/communities/acc9058e-b034-49d0-a008-af971a69c34d/invitations HTTP/1.1
Content-Type: application/json

{
    "members":[
        {
            "id":"4",
            "type":"user"
        }
    ],
    "role":"curator",
    "message":"<p>Hi</p>"
}

Response

HTTP/1.1 204 NO CONTENT

Remove members / leave community¶

DELETE /api/communities/{id}/members

Parameters

Name	Type	Location	Description
`id`	string	path	Community UUID identifier or slug e.g. `bd647379-23ea-477a-970f-201512ae5624` or `my-super-community`
`content-type`	string	header	- `application/json`
`members`	object	body	List of group members to delete.

Request

DELETE /api/communities/acc9058e-b034-49d0-a008-af971a69c34d/members HTTP/1.1
Content-Type: application/json

{
    "members": [
        {
            "type": "user",
            "id": "3"
        }
    ]
}

Response

HTTP/1.1 204 NO CONTENT

Update members¶

PUT /api/communities/{id}/members

Parameters

Name	Type	Location	Description
`id`	string	path	Community UUID identifier or slug e.g. `bd647379-23ea-477a-970f-201512ae5624` or `my-super-community`
`content-type`	string	header	- `application/json`
`members`	object	body	List of group members to add.
`role`	string	body	Set role of group (one of `reader`, `curator`, `manager`, `owner`).
`visible`	boolean	body	Set visibility (one of `true`, `false`)

Request

PUT /api/communities/acc9058e-b034-49d0-a008-af971a69c34d/members HTTP/1.1
Content-Type: application/json

{
    "members": [
        {
            "id": "admin",
            "type": "group"
        },
        {
            "id": "3",
            "type": "user"
        }
    ],
    "visible": false
    "role": "reader"
}

Response

HTTP/1.1 204 NO CONTENT

Update invitations¶

PUT /api/communities/{id}/invitations

Parameters

Name	Type	Location	Description
`id`	string	path	Community UUID identifier or slug e.g. `bd647379-23ea-477a-970f-201512ae5624` or `my-super-community`
`content-type`	string	header	- `application/json`
`members`	object	body	List of group members to add.
`role`	string	body	Set role of group (one of `reader`, `curator`, `manager`, `owner`).
`visible`	boolean	body	Set visibility (one of `true`, `false`)

Request

PUT /api/communities/acc9058e-b034-49d0-a008-af971a69c34d/invitations HTTP/1.1
Content-Type: application/json

{
    "members": [
        {
            "id": "3",
            "type": "user"
        }
    ],
    "role": "reader"
}

Response

HTTP/1.1 204 NO CONTENT