From f9d7f1faca413310b54403cf5fc44cb1e5326127 Mon Sep 17 00:00:00 2001 From: Ian Scott Date: Tue, 26 Mar 2024 16:37:16 -0400 Subject: [PATCH 1/5] Added available sort options for all REST API queries that allow sorting --- docs/reference/rest_api_awards.md | 5 +++++ docs/reference/rest_api_communities.md | 6 ++++-- docs/reference/rest_api_drafts_records.md | 8 ++++++-- docs/reference/rest_api_funders.md | 5 +++++ docs/reference/rest_api_members.md | 10 ++++++++-- docs/reference/rest_api_names.md | 5 +++++ docs/reference/rest_api_requests.md | 5 ++++- docs/reference/rest_api_users.md | 5 +++++ docs/reference/rest_api_vocabularies.md | 14 ++++++++++++++ 9 files changed, 56 insertions(+), 7 deletions(-) diff --git a/docs/reference/rest_api_awards.md b/docs/reference/rest_api_awards.md index 1331b980..80b8b51f 100644 --- a/docs/reference/rest_api_awards.md +++ b/docs/reference/rest_api_awards.md @@ -11,9 +11,14 @@ Query and retrieve entries from the [**awards** vocabulary](../customize/vocabul | Name | Type | Location | Description | | -------- | ------ | -------- | ------------------------------------ | | `q` | string | query | Search query used to filter results. | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` (default: `"bestmatch"` or `"title"`). | +| `size` | integer | query | Specify number of items in the results page (default: 10). | +| `page` | integer | query | Specify the page of results. | | `suggest` | string | query | "Search as you type" query. | | `accept` | string | header | - `application/json` | +Sort options for awards are configured on the vocabulary service class. 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 `"title"` sort is used. + **Query string syntax** The query string syntax is based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax), and can include the following search fields: diff --git a/docs/reference/rest_api_communities.md b/docs/reference/rest_api_communities.md index 0dc4cabc..284d77d6 100644 --- a/docs/reference/rest_api_communities.md +++ b/docs/reference/rest_api_communities.md @@ -293,12 +293,13 @@ Content-Type: application/json | Name | Type | Location | Description | |----------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results (default: newest). | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"` (default: `"newest"` or `"bestmatch"`). | | `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](../customize/search) 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** @@ -393,12 +394,13 @@ Same as `GET /api/communities` but with the authenticated user's communities in | Name | Type | Location | Description | |----------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results (default: newest). | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"` (default: `"newest"` or `"bestmatch"`). | | `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](../customize/search) 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** diff --git a/docs/reference/rest_api_drafts_records.md b/docs/reference/rest_api_drafts_records.md index cff76ffa..d792c611 100644 --- a/docs/reference/rest_api_drafts_records.md +++ b/docs/reference/rest_api_drafts_records.md @@ -1105,12 +1105,14 @@ Content-Type: application/json | Name | Type | Location | Description | | -------------- | ------- | -------- | ------------------------------------------------------------ | | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"`, `"mostviewed"`, `"mostdownloaded"` (default: `"newest"` or `"bestmatch"`). | | `size` | integer | query | Specify number of items in the results page (default: 10). | | `page` | integer | query | Specify the page of results. | | `allversions`   | boolean | query | Specify if all versions should be included (default: `False`, displays just latest version). | | `accept` | string | header | - `application/json` (default)
- `application/vnd.inveniordm.v1+json` | +Sort options for communities can be configured using the `RDM_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) 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. Queries sorted by `"mostviewed"` and `"mostdownloaded"` are in descending order. + **Request** ```http @@ -1772,12 +1774,14 @@ Used for interacting with the records and drafts you can edit. | Name | Type | Location | Description | | -------- | ------- | -------- | ------------------------------------------------------------ | | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"`, `"mostviewed"`, `"mostdownloaded"` (default: `"newest"` or `"bestmatch"`). | | `size` | integer | query | Specify number of items in the results page (default: 10). | | `page` | integer | query | Specify the page of results. | | `allversions`   | boolean | query | Specify if all versions should be included. | | `accept` | string | header | - `application/json` (default)
- `application/vnd.inveniordm.v1+json` | +Sort options for communities can be configured using the `RDM_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) 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. Queries sorted by `"mostviewed"` and `"mostdownloaded"` are in descending order. + **Request** ```http diff --git a/docs/reference/rest_api_funders.md b/docs/reference/rest_api_funders.md index 26fae50f..df863c0c 100644 --- a/docs/reference/rest_api_funders.md +++ b/docs/reference/rest_api_funders.md @@ -12,8 +12,13 @@ Query and retrieve entries from the [**funders** vocabulary](../customize/vocabu | -------- | ------ | -------- | ------------------------------------ | | `q` | string | query | Search query used to filter results. | | `suggest` | string | query | "Search as you type" query. | +| `sort` | string | query | Sort search results. 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. | | `accept` | string | header | - `application/json` | +Sort options for funders are configured on the vocabulary service class. 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 `"name"` sort is used. + **Query string syntax** The query string syntax is based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax), and can include the following search fields: diff --git a/docs/reference/rest_api_members.md b/docs/reference/rest_api_members.md index f0083cdb..ad004272 100644 --- a/docs/reference/rest_api_members.md +++ b/docs/reference/rest_api_members.md @@ -31,12 +31,14 @@ The following general restrictions apply to the member API: | `id` | string | path | Community UUID identifier | | `accept` | string | header | - `application/json` | | `q` | string | query | Search query used to filter results. | -| `sort` | string | query | Sort search results. | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (default: `"name"` or `"bestmatch"`). | | `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](../customize/search) 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** ```http @@ -157,6 +159,8 @@ Content-Type: application/json | `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** ```http @@ -205,13 +209,15 @@ Content-Type: application/json | `id` | string | path | Community UUID identifier | | `accept` | string | header | - `application/json` | | `q` | string | query | Search query used to filter results. | -| `sort` | string | query | Sort search results. | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (default: `"name"` or `"bestmatch"`). | | `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](../customize/search) 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** ```http diff --git a/docs/reference/rest_api_names.md b/docs/reference/rest_api_names.md index 7c9a7840..3c11c702 100644 --- a/docs/reference/rest_api_names.md +++ b/docs/reference/rest_api_names.md @@ -11,9 +11,14 @@ Query and retrieve entries from the [**names** vocabulary](../customize/vocabula | Name | Type | Location | Description | | -------- | ------ | -------- | ------------------------------------ | | `q` | string | query | Search query used to filter results. | +| `sort` | string | query | Sort search results. 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. | | `suggest` | string | query | "Search as you type" query. | | `accept` | string | header | - `application/json` | +Sort options for names are configured on the vocabulary service class. 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 `"name"` sort is used. + **Query string syntax** The query string syntax is based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax), and can include the following search fields: diff --git a/docs/reference/rest_api_requests.md b/docs/reference/rest_api_requests.md index b63c2981..1f16b641 100644 --- a/docs/reference/rest_api_requests.md +++ b/docs/reference/rest_api_requests.md @@ -138,11 +138,13 @@ Used for listing all requests you can interact with. | Name | Type | Location | Description | | -------------- | ------- | -------- | ------------------------------------------------------------ | | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (default: `"newest"` or `"bestmatch"`). | | `size` | integer | query | Specify number of items in the results page (default: 10). | | `page` | integer | query | Specify the page of results. | | `accept` | string | header | - `application/json` (default)
- `application/vnd.inveniordm.v1+json` | +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 `"newest"`. In this case a `"bestmatch"` value is ignored and the default `"newest"` sort is used. + **Request** ```http @@ -188,6 +190,7 @@ Content-Type: application/json ], "total": 2 }, + "sortBy": "newest", "links": { "self": "{scheme+hostname}/api/requests?page=1&size=25&sort=newest" } diff --git a/docs/reference/rest_api_users.md b/docs/reference/rest_api_users.md index 7426ff79..4aa16836 100644 --- a/docs/reference/rest_api_users.md +++ b/docs/reference/rest_api_users.md @@ -26,8 +26,13 @@ Search for users | Name | Type | Location | Description | | -------- | ------ | -------- | ------------------------------------ | | `q` | string | query | Search query used to filter results. | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"username"`, `"email"`, `"domain"`, `"newest"`, `"oldest"`, `"updated"` (default: `"newest"` or `"bestmatch"`). | +| `size` | integer | query | Specify number of items in the results page (default: 10). | +| `page` | integer | query | Specify the page of results. | | `accept` | string | header | - `application/json` | +Sort options for users can be configured using the `USERS_RESOURCES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) 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 `"newest"`. In this case a `"bestmatch"` value is ignored and the default `"newest"` sort is used. + **Query string syntax** The query string syntax is based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). diff --git a/docs/reference/rest_api_vocabularies.md b/docs/reference/rest_api_vocabularies.md index fb07a0c9..9b563548 100644 --- a/docs/reference/rest_api_vocabularies.md +++ b/docs/reference/rest_api_vocabularies.md @@ -33,6 +33,20 @@ Specifically for the `application/vnd.inveniordm.v1+json` format: The API uses a locale matching algorithm, that will do its best effort to translate the vocabulary record's title and description. +The sort options available vary depending on the vocabulary being searched. These cannot presently be configured via config variables but are set in the service configuration for each vocabulary service. The default sort options are used where a vocabulary service has not defined its own: + +| Vocabulary | Available sort options | Default | Default without a query string | +| ---------- | ---------------------- | ------- | ------------------------------ | +| default | `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"title"` | +| affiliations | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` | +| awards | `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"title"` | +| funders | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` | +| names | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` | +| subjects* | `"bestmatch"`, `"subject"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"subject"` | + +(\* Subjects are available only at the `/api/subjects` endpoint, but are included here for reference since they are provided by a vocabulary service.) + + **Request** ```http From 6c992de33fd748041eb96a41bd524047943d3b76 Mon Sep 17 00:00:00 2001 From: Ian Scott Date: Sat, 6 Apr 2024 11:03:29 -0400 Subject: [PATCH 2/5] Minor fixes to default orders and link syntax --- docs/reference/rest_api_communities.md | 8 ++++---- docs/reference/rest_api_drafts_records.md | 8 ++++---- docs/reference/rest_api_members.md | 8 ++++---- docs/reference/rest_api_requests.md | 2 +- docs/reference/rest_api_users.md | 4 ++-- docs/reference/rest_api_vocabularies.md | 16 ++-------------- 6 files changed, 17 insertions(+), 29 deletions(-) diff --git a/docs/reference/rest_api_communities.md b/docs/reference/rest_api_communities.md index 284d77d6..1228c33b 100644 --- a/docs/reference/rest_api_communities.md +++ b/docs/reference/rest_api_communities.md @@ -293,13 +293,13 @@ Content-Type: application/json | Name | Type | Location | Description | |----------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"` (default: `"newest"` or `"bestmatch"`). | +| `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](../customize/search) 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. +Sort options for communities can be configured using the `COMMUNITIES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) 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** @@ -394,13 +394,13 @@ Same as `GET /api/communities` but with the authenticated user's communities in | Name | Type | Location | Description | |----------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"` (default: `"newest"` or `"bestmatch"`). | +| `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](../customize/search) 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. +Sort options for communities can be configured using the `COMMUNITIES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) 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** diff --git a/docs/reference/rest_api_drafts_records.md b/docs/reference/rest_api_drafts_records.md index d792c611..4e737079 100644 --- a/docs/reference/rest_api_drafts_records.md +++ b/docs/reference/rest_api_drafts_records.md @@ -1105,13 +1105,13 @@ Content-Type: application/json | Name | Type | Location | Description | | -------------- | ------- | -------- | ------------------------------------------------------------ | | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"`, `"mostviewed"`, `"mostdownloaded"` (default: `"newest"` or `"bestmatch"`). | +| `sort` | string | query | Sort search results. Customizable. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"`, `"mostviewed"`, `"mostdownloaded"` (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. | | `allversions`   | boolean | query | Specify if all versions should be included (default: `False`, displays just latest version). | | `accept` | string | header | - `application/json` (default)
- `application/vnd.inveniordm.v1+json` | -Sort options for communities can be configured using the `RDM_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) 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. Queries sorted by `"mostviewed"` and `"mostdownloaded"` are in descending order. +Sort options for records can be configured using the `RDM_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) 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. Queries sorted by `"mostviewed"` and `"mostdownloaded"` are in descending order. **Request** @@ -1774,13 +1774,13 @@ Used for interacting with the records and drafts you can edit. | Name | Type | Location | Description | | -------- | ------- | -------- | ------------------------------------------------------------ | | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"`, `"mostviewed"`, `"mostdownloaded"` (default: `"newest"` or `"bestmatch"`). | +| `sort` | string | query | Sort search results. Customizable. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"`, `"mostviewed"`, `"mostdownloaded"` (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. | | `allversions`   | boolean | query | Specify if all versions should be included. | | `accept` | string | header | - `application/json` (default)
- `application/vnd.inveniordm.v1+json` | -Sort options for communities can be configured using the `RDM_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) 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. Queries sorted by `"mostviewed"` and `"mostdownloaded"` are in descending order. +Sort options for records can be configured using the `RDM_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) 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. Queries sorted by `"mostviewed"` and `"mostdownloaded"` are in descending order. **Request** diff --git a/docs/reference/rest_api_members.md b/docs/reference/rest_api_members.md index ad004272..b9e8df26 100644 --- a/docs/reference/rest_api_members.md +++ b/docs/reference/rest_api_members.md @@ -31,13 +31,13 @@ The following general restrictions apply to the member API: | `id` | string | path | Community UUID identifier | | `accept` | string | header | - `application/json` | | `q` | string | query | Search query used to filter results. | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (default: `"name"` or `"bestmatch"`). | +| `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](../customize/search) 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. +Sort options for community members can be configured using the `COMMUNITIES_MEMBERS_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) 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** @@ -209,14 +209,14 @@ Content-Type: application/json | `id` | string | path | Community UUID identifier | | `accept` | string | header | - `application/json` | | `q` | string | query | Search query used to filter results. | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (default: `"name"` or `"bestmatch"`). | +| `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](../customize/search) 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. +Sort options for community members can be configured using the `COMMUNITIES_INVITATIONS_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) 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** diff --git a/docs/reference/rest_api_requests.md b/docs/reference/rest_api_requests.md index 1f16b641..a0c1aa30 100644 --- a/docs/reference/rest_api_requests.md +++ b/docs/reference/rest_api_requests.md @@ -138,7 +138,7 @@ Used for listing all requests you can interact with. | Name | Type | Location | Description | | -------------- | ------- | -------- | ------------------------------------------------------------ | | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (default: `"newest"` or `"bestmatch"`). | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` (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. | | `accept` | string | header | - `application/json` (default)
- `application/vnd.inveniordm.v1+json` | diff --git a/docs/reference/rest_api_users.md b/docs/reference/rest_api_users.md index 4aa16836..195fd5b3 100644 --- a/docs/reference/rest_api_users.md +++ b/docs/reference/rest_api_users.md @@ -26,12 +26,12 @@ Search for users | Name | Type | Location | Description | | -------- | ------ | -------- | ------------------------------------ | | `q` | string | query | Search query used to filter results. | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"username"`, `"email"`, `"domain"`, `"newest"`, `"oldest"`, `"updated"` (default: `"newest"` or `"bestmatch"`). | +| `sort` | string | query | Sort search results. Customizable. Built-in options are `"bestmatch"`, `"username"`, `"email"`, `"domain"`, `"newest"`, `"oldest"`, `"updated"` (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. | | `accept` | string | header | - `application/json` | -Sort options for users can be configured using the `USERS_RESOURCES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) 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 `"newest"`. In this case a `"bestmatch"` value is ignored and the default `"newest"` sort is used. +Sort options for users can be configured using the `USERS_RESOURCES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) 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 `"newest"`. In this case a `"bestmatch"` value is ignored and the default `"newest"` sort is used. **Query string syntax** diff --git a/docs/reference/rest_api_vocabularies.md b/docs/reference/rest_api_vocabularies.md index 9b563548..51fcdd32 100644 --- a/docs/reference/rest_api_vocabularies.md +++ b/docs/reference/rest_api_vocabularies.md @@ -19,7 +19,7 @@ are supported: | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | | `suggest` | string | query | One or more words used to suggest records as the user types (i.e. auto-complete). | | `tags` | string | query | Filter results to the tag | -| `sort` | string | query | Sort search results. | +| `sort` | string | query | Sort search results. Unless overridden by a specific vocabulary, the built-in options are `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` (default: `"bestmatch"` or `"title"`). | | | `size` | integer | query | Specify number of items in the results page (default: 10). | | `page` | integer | query | Specify the page of results. | | `accept` | string | header | - `application/json` (default)
- `application/vnd.inveniordm.v1+json` | @@ -33,19 +33,7 @@ Specifically for the `application/vnd.inveniordm.v1+json` format: The API uses a locale matching algorithm, that will do its best effort to translate the vocabulary record's title and description. -The sort options available vary depending on the vocabulary being searched. These cannot presently be configured via config variables but are set in the service configuration for each vocabulary service. The default sort options are used where a vocabulary service has not defined its own: - -| Vocabulary | Available sort options | Default | Default without a query string | -| ---------- | ---------------------- | ------- | ------------------------------ | -| default | `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"title"` | -| affiliations | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` | -| awards | `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"title"` | -| funders | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` | -| names | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` | -| subjects* | `"bestmatch"`, `"subject"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"subject"` | - -(\* Subjects are available only at the `/api/subjects` endpoint, but are included here for reference since they are provided by a vocabulary service.) - +The sort options available vary depending on the vocabulary being searched. These cannot presently be configured via config variables but are set in the service configuration for each vocabulary service. The default sort options are used where a vocabulary service has not defined its own. **Request** From dc04caab5d69df184267518a8493136fa2413a49 Mon Sep 17 00:00:00 2001 From: "Ian W. Scott" Date: Wed, 27 Mar 2024 12:11:43 -0400 Subject: [PATCH 3/5] Update docs/reference/rest_api_awards.md Co-authored-by: Guillaume Viger --- docs/reference/rest_api_awards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/rest_api_awards.md b/docs/reference/rest_api_awards.md index 80b8b51f..b6787327 100644 --- a/docs/reference/rest_api_awards.md +++ b/docs/reference/rest_api_awards.md @@ -11,7 +11,7 @@ Query and retrieve entries from the [**awards** vocabulary](../customize/vocabul | Name | Type | Location | Description | | -------- | ------ | -------- | ------------------------------------ | | `q` | string | query | Search query used to filter results. | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` (default: `"bestmatch"` or `"title"`). | +| `sort` | string | query | Sort search results. Customizable. Built-in options are `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` (default: `"bestmatch"` or `"title"`). | | `size` | integer | query | Specify number of items in the results page (default: 10). | | `page` | integer | query | Specify the page of results. | | `suggest` | string | query | "Search as you type" query. | From 988bb5dc6b3cf55f816b13f0dbe5962b33b620c6 Mon Sep 17 00:00:00 2001 From: Ian Scott Date: Mon, 8 Apr 2024 14:57:07 -0400 Subject: [PATCH 4/5] Fixing merge conflict for rebase --- docs/reference/rest_api_communities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/rest_api_communities.md b/docs/reference/rest_api_communities.md index 1228c33b..0e8c43ad 100644 --- a/docs/reference/rest_api_communities.md +++ b/docs/reference/rest_api_communities.md @@ -394,7 +394,7 @@ Same as `GET /api/communities` but with the authenticated user's communities in | Name | Type | Location | Description | |----------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#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"`). | +| `sort` | string | query | Sort search results. 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. | From fd4c3a915cc610a3d588692260914f1f95cf0a34 Mon Sep 17 00:00:00 2001 From: Ian Scott Date: Mon, 8 Apr 2024 16:00:02 -0400 Subject: [PATCH 5/5] Fixed two regressions that arose from the merge process during rebase. --- docs/reference/rest_api_awards.md | 2 +- docs/reference/rest_api_communities.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/rest_api_awards.md b/docs/reference/rest_api_awards.md index b6787327..b157c147 100644 --- a/docs/reference/rest_api_awards.md +++ b/docs/reference/rest_api_awards.md @@ -11,7 +11,7 @@ Query and retrieve entries from the [**awards** vocabulary](../customize/vocabul | Name | Type | Location | Description | | -------- | ------ | -------- | ------------------------------------ | | `q` | string | query | Search query used to filter results. | -| `sort` | string | query | Sort search results. Customizable. Built-in options are `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` (default: `"bestmatch"` or `"title"`). | +| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` (default: `"bestmatch"` or `"title"`). | | `size` | integer | query | Specify number of items in the results page (default: 10). | | `page` | integer | query | Specify the page of results. | | `suggest` | string | query | "Search as you type" query. | diff --git a/docs/reference/rest_api_communities.md b/docs/reference/rest_api_communities.md index 0e8c43ad..1228c33b 100644 --- a/docs/reference/rest_api_communities.md +++ b/docs/reference/rest_api_communities.md @@ -394,7 +394,7 @@ Same as `GET /api/communities` but with the authenticated user's communities in | Name | Type | Location | Description | |----------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `q` | string | query | Search query used to filter results based on [ElasticSearch's query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax). | -| `sort` | string | query | Sort search results. Built-in options are `"bestmatch"`, `"newest"`, `"oldest"`, `"updated-desc"`, `"updated-asc"`, `"version"` (default: `"bestmatch"` or `"newest"`). | +| `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. |