Nothing Special   »   [go: up one dir, main page]

Skip to content

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