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