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

Skip to content

Communities

Communities

Create a Community

POST /api/communities

Parameters

Name Type Location Description
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
access object body Access of the community.
slug string body Required, url-compatible, max 100 char. The identifier of the community that will be used in the community's URL.
metadata object body Metadata of the community.

Community access

Name Type Location Description
visibility string body Required, one of "public" or "restricted". Visible by the public or restricted to those who have access.
member_policy string body Required, one of "open" or "closed". Can people request to be part of the community (open) or not (closed)?
record_policy string body Required, one of "open" or "closed". Can community's members submit a record to the community without a review (open), or a review is always necessary (closed)?
owned_by array body Array of Objects of the form: {"user": <user_id> }. Community owners (admins).

Community metadata

Name Type Location Description
title string body Required, max 250 char. Human readable title of the community.
description string body Max 2000 char. Short description of the community.
curation_policy string body Max 2000 char, html allowed. Description of how records are curated for this community.
type object body Object with an id and optionally a title, in the form {"id": "event", "title: { "en": "example_title"}}
website string body URL. URL to external website.
organizations array body Array of Objects of the form: {"id": <ROR id>} or {"name": <string>}. Organizations related to the community.

Request

POST /api/communities HTTP/1.1
Content-Type: application/json

{
    "access": {
            "visibility": "public",
            "member_policy": "open",
            "record_policy": "open"
            },
    "slug": "my_community_identifier",
    "metadata": {
            "title": "My Community",
            "description": "This is an example Community.",
            "type": {
                "id": "event"
            },
            "curation_policy": "This is the kind of records we accept.",
            "page": "Information for my community.",
            "website": "https://inveniosoftware.org/",
            "organizations": [{
                    "name": "My Org"
            }]
    }
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "access": {
    "visibility": "public",
    "member_policy": "open",
    "record_policy": "open",
    "owned_by": [
      {
          "user": {user-id}
      }
    ],
  },
  "created": "2020-11-27 10:52:23.945755",
  "updated": "2020-11-27 10:52:23.945755",
  "slug": "my_community_identifier",
  "id": "399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3",
  "revision_id": 1,
  "links": {
    "self": "{scheme+hostname}/api/communities/{id}",
    "self_html": "{scheme+hostname}/communities/{id}",
    "settings_html": "{scheme+hostname}/communities/{id}/settings",
    "logo": "{scheme+hostname}/communities/{id}/logo",
    "rename": "{scheme+hostname}/communities/{id}",
    "members": "{scheme+hostname}/communities/{id}/members",
    "public_members": "{scheme+hostname}/communities/{id}/members/public",
    "invitations": "{scheme+hostname}/communities/{id}/invitations",
    "requests": "{scheme+hostname}/communities/{id}/requests"
  },
  "metadata": {
    "title": "My Community",
    "description": "This is an example Community.",
    "type": {
        "id": "event"
    },
    "curation_policy": "This is the kind of records we accept.",
    "page": "Information for my community.",
    "website": "https://inveniosoftware.org/",
    "organizations": [{
      "name": "CERN",
    }]
  }
}

Update a Community

PUT /api/communities/<com_slug>

Parameters

Name Type Location Description
com_slug string path Identifier of the community, e.g. my_community
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

PUT /api/communities/{id} HTTP/1.1
Content-Type: application/json

{
  "access": {
    "visibility": "public",
    "member_policy": "open",
    "record_policy": "open"
  },
  "slug": "my_community_identifier",
  "metadata": {
    "title": "My Updated Community",
    "description": "This is an example Community.",
    "type": {
        "id": "event"
    },
    "curation_policy": "This is the kind of records we accept.",
    "page": "Information for my community.",
    "website": "https://inveniosoftware.org/",
    "organizations": [{
      "name": "CERN",
    }]
  }
}

Response

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

{
  "access": {
    "visibility": "public",
    "member_policy": "open",
    "record_policy": "open"
  },
  "created": "2020-11-27 10:52:23.945755",
  "updated": "2020-11-27 10:55:23.945868",
  "slug": "my_community_identifier",
  "id": "399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3",
  "revision_id": 2,
  "links": {
    "self": "{scheme+hostname}/api/communities/{id}",
    "self_html": "{scheme+hostname}/communities/{id}",
    "settings_html": "{scheme+hostname}/communities/{id}/settings",
    "logo": "{scheme+hostname}/communities/{id}/logo",
    "rename": "{scheme+hostname}/communities/{id}",
    "members": "{scheme+hostname}/communities/{id}/members",
    "public_members": "{scheme+hostname}/communities/{id}/members/public",
    "invitations": "{scheme+hostname}/communities/{id}/invitations",
    "requests": "{scheme+hostname}/communities/{id}/requests"
  },
  "metadata": {
    "title": "My Updated Community",
    "description": "This is an example Community.",
    "type": {
        "id": "event"
    },
    "curation_policy": "This is the kind of records we accept.",
    "page": "Information for my community.",
    "website": "https://inveniosoftware.org/",
    "organizations": [{
      "name": "CERN"
    }]
  }
}

Delete a Community

DELETE /api/communities/{id}

Parameters

Name Type Location Description
id string path UUID or slug of the community e.g. 399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3 or 'my-super-community'
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

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

Response

HTTP/1.1 204 No Content

Get a Community

GET /api/communities/{id}

Parameters

Name Type Location Description
id string path UUID or slug of the community e.g. 399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3 or my-super-community
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

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

Response:

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

{
  "access": {
    "visibility": "public",
    "member_policy": "open",
    "record_policy": "open"
  },
  "created": "2020-11-27 10:52:23.945755",
  "updated": "2020-11-27 10:55:23.945868",
  "slug": "my_community_identifier",
  "id": "399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3",
  "revision_id": 2,
  "links": {
    "self": "{scheme+hostname}/api/communities/{id}",
    "self_html": "{scheme+hostname}/communities/{id}",
    "settings_html": "{scheme+hostname}/communities/{id}/settings",
    "logo": "{scheme+hostname}/communities/{id}/logo",
    "rename": "{scheme+hostname}/communities/{id}",
    "members": "{scheme+hostname}/communities/{id}/members",
    "public_members": "{scheme+hostname}/communities/{id}/members/public",
    "invitations": "{scheme+hostname}/communities/{id}/invitations",
    "requests": "{scheme+hostname}/communities/{id}/requests",
    "featured": "{scheme+hostname}/communities/{id}/featured"
  },
  "metadata": {
    "title": "My Updated Community",
    "description": "This is an example Community.",
    "type": {
        "id": "event"
    },
    "curation_policy": "This is the kind of records we accept.",
    "page": "Information for my community.",
    "website": "https://inveniosoftware.org/",
    "organizations": [{
      "name": "CERN"
    }]
  }
}

Search Communities

GET /api/communities

Parameters

Name Type Location Description
q string query Search query used to filter results based on ElasticSearch's query string syntax.
sort string query Sort search results. Customizable. Built-in options are "bestmatch", "newest", "oldest", "updated-desc", "updated-asc", "version" (default: "bestmatch" or "newest").
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
type string query Specify community type as one of organization, event, topic or project.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Sort options for communities can be configured using the COMMUNITIES_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. Otherwise "bestmatch" is ignored and the default "newest" sort is used.

Request

GET /api/communities HTTP/1.1
Accept: application/json

Response

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

{
  "aggregations": {
    "type": {
      "buckets": [
      {
        "doc_count": 4,
        "key": "event"
      },
      {
        ...
      }],
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0
    }
  },
  "hits": {
    "hits": [{
      "access": {
        "visibility": "public",
        "member_policy": "open",
        "record_policy": "open"
      },
      "created": "2020-11-27 10:52:23.945755",
      "updated": "2020-11-27 10:55:23.945868",
      "slug": "my_community_identifier",
      "id": "399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3",
      "revision_id": 2,
      "links": {
        "self": "{scheme+hostname}/api/communities/{id}",
        "self_html": "{scheme+hostname}/communities/{id}",
        "settings_html": "{scheme+hostname}/communities/{id}/settings",
        "logo": "{scheme+hostname}/communities/{id}/logo",
        "rename": "{scheme+hostname}/communities/{id}",
        "members": "{scheme+hostname}/communities/{id}/members",
        "public_members": "{scheme+hostname}/communities/{id}/members/public",
        "invitations": "{scheme+hostname}/communities/{id}/invitations",
        "requests": "{scheme+hostname}/communities/{id}/requests"
      },
      "metadata": {
        "title": "My Updated Community",
        "description": "This is an example Community.",
        "type": {
            "id": "event"
        },
        "curation_policy": "This is the kind of records we accept.",
        "page": "Information for my community.",
        "website": "https://inveniosoftware.org/",
        "organizations": [{
          "name": "CERN"
        }]
      }
    },
    {
      ...
    },
    {
      ...
    }]
  "total": 16
  },
  "links": {
    "self": "{scheme+hostname}/api/communities?{params}"
  },
  "sortBy": "newest"
}

Each hit looks like a community above.

Search User Communities

Same as GET /api/communities but with the authenticated user's communities in the search results.

GET /api/user/communities

Parameters

Name Type Location Description
q string query Search query used to filter results based on ElasticSearch's query string syntax.
sort string query Sort search results. Customizable. Built-in options are "bestmatch", "newest", "oldest", "updated-desc", "updated-asc", "version" (default: "bestmatch" or "newest").
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
type string query Specify community type as one of organization, event, topic or project.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Sort options for communities can be configured using the COMMUNITIES_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. Otherwise "bestmatch" is ignored and the default "newest" sort is used.

Request

GET /api/user/communities HTTP/1.1
Accept: application/json

Response

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

{
  "aggregations": {...},
  "hits": {...},
  "links": {...},
  "sortBy": "newest"
}

Rename a Community

POST /api/communities/{id}/rename

Parameters

Name Type Location Description
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
id string path UUID or slug of the community e.g. 399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3 or my-super-community

Request

POST /api/communities/{id}/rename HTTP/1.1
Content-Type: application/json

{
  "access": {
    "visibility": "public",
    "member_policy": "open",
    "record_policy": "open"
  },
  "slug": "my_new_community_identifier",
  "metadata": {
    "title": "My Community",
    "description": "This is an example Community.",
    "type": "event",
    "curation_policy": "This is the kind of records we accept.",
    "page": "Information for my community.",
    "website": "https://inveniosoftware.org/",
    "organizations": [{
      "name": "CERN",
    }]
  }
}

Response

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

{
  "access": {
    "visibility": "public",
    "member_policy": "open",
    "record_policy": "open",
    "owned_by": [
      {
          "user": {user-id}
      }
    ],
  },
  "created": "2020-11-27 10:52:23.945755",
  "updated": "2020-11-27 10:52:23.945755",
  "slug": "my_new_community_identifier",
  "id": "399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3",
  "revision_id": 2,
  "links": {
    "self": "{scheme+hostname}/api/communities/{id}",
    "self_html": "{scheme+hostname}/communities/{id}",
    "settings_html": "{scheme+hostname}/communities/{id}/settings",
    "logo": "{scheme+hostname}/communities/{id}/logo",
    "rename": "{scheme+hostname}/communities/{id}",
    "members": "{scheme+hostname}/communities/{id}/members",
    "public_members": "{scheme+hostname}/communities/{id}/members/public",
    "invitations": "{scheme+hostname}/communities/{id}/invitations",
    "requests": "{scheme+hostname}/communities/{id}/requests"
  },
  "metadata": {
    "title": "My Community",
    "description": "This is an example Community.",
    "type": "event",
    "curation_policy": "This is the kind of records we accept.",
    "page": "Information for my community.",
    "website": "https://inveniosoftware.org/",
    "organizations": [{
      "name": "CERN",
    }]
  }
}

PUT /api/communities/{id}/logo

Parameters

Name Type Location Description
id string path UUID or slug of the community e.g. 399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3 or my-super-community
content-type string header Should always be application/octet-stream.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

PUT /api/communities/{id}/logo HTTP/1.1
Content-Type: application/octet-stream

<...file binary data...>

Response

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

{
  "bucket_id": "d3c493fd",
  "checksum": "md5:96d6f2e7e1f705ab5e59c84a6dc009b2",
  "created": "2021-04-26 10:52:23.945755",
  "file_id": "d2a7adb5",
  "key": "logo",
  "links": {"self": "{scheme+hostname}/api/communities/{id}/logo"},
  "metadata": None,
  "mimetype": "application/octet-stream",
  "size": file_size,
  "status": "completed",
  "storage_class": "S",
  "updated": "2021-04-26 10:52:24.562652",
  "version_id": "b95ead95"
 }

GET /api/communities/{id}/logo

Parameters

Name Type Location Description
id string path UUID or slug of the community e.g. 399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3 or my-super-community

Request

GET /api/communities/{id}/logo HTTP/1.1

Response

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

{
  "data": <...file binary data...>
}

DELETE /api/communities/{id}/logo

Parameters

Name Type Location Description
id string path UUID or slug of the community e.g. 399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3 or my-super-community

Request

DELETE /api/communities/{id}/logo HTTP/1.1

Response

HTTP/1.1 204 No Content

Get Community Records

GET /api/communities/{id}/records

Parameters

Name Type Location Description
id string path UUID or slug of the community e.g. 399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3 or my-super-community

Request

GET /api/communities/{id}/records HTTP/1.1

Response

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

{
    "hits": {
        "hits": [
            {...<record-1>...}
        ],
        "total": 1
    },
    "aggregations": {
        "access_status": {
            "buckets": [
                {
                    "key": "metadata-only",
                    "doc_count": 1,
                    "label": "Metadata-only",
                    "is_selected": false
                }
            ],
            "label": "Access status"
        },
        "resource_type": {
            "buckets": [
                {
                    "key": "dataset",
                    "doc_count": 1,
                    "label": "Dataset",
                    "is_selected": false,
                    "inner": {
                        "buckets": []
                    }
                }
            ],
            "label": "Resource types"
        }
    },
    "sortBy": "newest",
    "links": {
        "self": "https://127.0.0.1:5000/api/communities/399a3cdc-d2ba-4f63-8b3a-9c2c977a5dd3/records?page=1&size=25&sort=newest"
    }
}

Error Responses of Community

POST /api/communities

Parameters

Name Type Location Description
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Request

POST /api/communities HTTP/1.1
Content-Type: application/json

{
  "access": { },
  "slug": "my_community_identifier",
  "metadata": { }
}

Response

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
  "errors": [
    {
      "field": "metadata.title",
      "messages": [
        "Missing data for required field."
      ]
    },
  ],
 "message": "A validation error occurred.",
 "status": 400
}

The goal of featured communities is to increase the level of awareness for a community. This could be due to special research output, because a community is new or any other reason a community should be put in the spotlight.

Hint

Only public communities may be featured, as they can be accessed by everyone.

Only the search is available to any user. Other endpoints require the system_process permission need.

GET /api/communities/featured

Parameters

Name Type Location Description
q string query Search query used to filter results based on ElasticSearch's query string syntax.
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
type string query Specify community type as one of organization, event, topic or project.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Only communities with a featured timestamp before the current time are retrieved. They are sorted by the beginning of their latest featured timestamp (e.g. A is featured starting with 2022-06-01, B is featured starting with 2022-06-03 then the order will be [B, A]).

Request

GET /api/communities HTTP/1.1
Accept: application/json

Response

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

{
  "hits": {
    "hits": [
      {
        "created": "2022-06-03T10:04:14.837956+00:00",
        "links": {
          "self": "{scheme+hostname}/api/communities/21c0c843-c3c1-40df-9bcd-225b9a4f9021",
          "self_html": "{scheme+hostname}/communities/c2-id",
          "settings_html": "{scheme+hostname}/communities/c2-id/settings",
          "logo": "{scheme+hostname}/api/communities/21c0c843-c3c1-40df-9bcd-225b9a4f9021/logo",
          "rename": "{scheme+hostname}/api/communities/21c0c843-c3c1-40df-9bcd-225b9a4f9021/rename",
          "members": "{scheme+hostname}/api/communities/21c0c843-c3c1-40df-9bcd-225b9a4f9021/members",
          "public_members": "{scheme+hostname}/api/communities/21c0c843-c3c1-40df-9bcd-225b9a4f9021/members/public",
          "invitations": "{scheme+hostname}/api/communities/21c0c843-c3c1-40df-9bcd-225b9a4f9021/invitations",
          "requests": "{scheme+hostname}/api/communities/21c0c843-c3c1-40df-9bcd-225b9a4f9021/requests"
        },
        "metadata": {
          "title": "My Community"
        },
        "id": "21c0c843-c3c1-40df-9bcd-225b9a4f9021",
        "updated": "2022-06-03T10:04:14.852380+00:00",
        "access": {
          "member_policy": "open",
          "record_policy": "open",
          "visibility": "public"
        },
        "revision_id": 2,
        "slug": "c2-id"
      },
      {
        "created": "2022-06-03T10:04:14.659785+00:00",
        "links": {
          "self": "{scheme+hostname}/api/communities/9b44aa91-de2b-4551-97ff-8a9cb25e5752",
          "self_html": "{scheme+hostname}/communities/1654243454-614428",
          "settings_html": "{scheme+hostname}/communities/1654243454-614428/settings",
          "logo": "{scheme+hostname}/api/communities/9b44aa91-de2b-4551-97ff-8a9cb25e5752/logo",
          "rename": "{scheme+hostname}/api/communities/9b44aa91-de2b-4551-97ff-8a9cb25e5752/rename",
          "members": "{scheme+hostname}/api/communities/9b44aa91-de2b-4551-97ff-8a9cb25e5752/members",
          "public_members": "{scheme+hostname}/api/communities/9b44aa91-de2b-4551-97ff-8a9cb25e5752/members/public",
          "invitations": "{scheme+hostname}/api/communities/9b44aa91-de2b-4551-97ff-8a9cb25e5752/invitations",
          "requests": "{scheme+hostname}/api/communities/9b44aa91-de2b-4551-97ff-8a9cb25e5752/requests"
        },
        "metadata": {
          "title": "My Community"
        },
        "id": "9b44aa91-de2b-4551-97ff-8a9cb25e5752",
        "updated": "2022-06-03T10:04:14.685074+00:00",
        "access": {
          "member_policy": "open",
          "record_policy": "open",
          "visibility": "public"
        },
        "revision_id": 2,
        "slug": "1654243454-614428"
      }
    ],
    "total": 2
  },
  "aggregations": {
    "type": {
      "buckets": [],
      "label": "Type"
    },
    "visibility": {
      "buckets": [
        {
          "key": "public",
          "doc_count": 2,
          "label": "Public",
          "is_selected": false
        }
      ],
      "label": "Visibility"
    }
  },
  "sortBy": "featured",
  "links": {
    "self": "{scheme+hostname}/api/communities/featured?page=1&size=25&sort=featured"
  }
}

Create a Featured Community Entry

POST /api/communities/{id}/featured

Parameters

Name Type Location Description
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
community_id string path ID of the community.
start_date string body Required, ISO 8601 DateTime format in UTC (YYYY-MM-DDTHH:MM:SS.ssssssZ). The community will be featured from this point in time onwards.

Request

POST /api/communities/{id}/featured HTTP/1.1
Content-Type: application/json

{
  "start_date": "2022-06-03 10:52:23.945755"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "start_date": "2022-06-03 10:52:23.945755"
  "id": 1
}

GET /api/communities/{id}/featured

Parameters

Name Type Location Description
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
id string path ID of the community.

Request

GET /api/communities/{id}/featured HTTP/1.1

Response

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

{
  "hits": {
    "hits": [
      {
        "start_date": "2022-06-03T10:32:42.207652",
        "id": 8
      },
      {
        "start_date": "2022-06-04T10:32:42.207662",
        "id": 9
      }
    ],
    "total": 2
  }
}

Update a Featured Community Entry

PUT /api/communities/{id}/featured/<featured_entry_id>

Parameters

Name Type Location Description
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
id string path ID of the community.
featured_entry_id string path ID of the featured entry.
start_date string body Required, datetime in iso format. Community will be featured from this point in time onwards.

Request

PUT /api/communities/{id}/featured/<featured_entry_id> HTTP/1.1
Content-Type: application/json

{
  "start_date": "2022-06-03 10:52:23.945755"
}

Response

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

{
  "start_date": "2022-06-03 10:52:23.945755"
  "id": <featured_entry_id>
}

Delete a Featured Community Entry

DELETE /api/communities/{id}/featured/<featured_entry_id>

Parameters

Name Type Location Description
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json
id string path ID of the community.
featured_entry_id string path ID of the featured entry.

Request

DELETE /api/communities/{id}/featured/<featured_entry_id> HTTP/1.1

Response

HTTP/1.1 204 No Content