Simple search
Introduction
A simple search lets a user find items in a collection with a keyword query and a sort order. It is meant for quick, straightforward searching.
A simple search is optional. An integration layer MAY implement it, depending on its requirements. An integration layer that needs filters, such as date ranges, geolocation or facet values, can implement an advanced search instead.
A collection that supports a simple search advertises the https://specs.nde.nl/rest/v1/simple-search capability.
Endpoint: Simple search
A simple search is not a separate endpoint. It uses the endpoint that retrieves a collection or a page. For example, a simple search can be applied to a curated collection or to a facet collection.
HTTP request
GET /{version}/{...collections}?q={q}&orderBy={orderBy}&size={size}&page={page}
Path parameters
| Name | Data type | Cardinality | Description |
|---|---|---|---|
version | string | 1 | The version of the API. Example: v1. |
...collections | string | 1 or more | The path identifier(s) of the context collection. Example: collections/objects. |
Query parameters
| Name | Data type | Cardinality | Description |
|---|---|---|---|
q | string | 0 or 1 | A keyword query for filtering the items. The integration layer defines the minimum and maximum length and how the query is matched. |
orderBy | string | 0 or 1 | The sorting order of the items: a comma-separated list of sort criteria, in priority order. Each criterion is property or property:order, where property is relevance or value and order is asc or desc. Example: relevance:desc,value:asc. relevance typically expresses how well an item matches the keyword query (q). An integration layer MAY also apply its own relevance rules when q is missing. The integration layer defines which property value sorts on (e.g. the name of an entity). |
size | number | 0 or 1 | The maximum number of items to retrieve. The minimum is 1. The integration layer defines the maximum. |
page | string | 0 or 1 | The page to retrieve. If the collection has a pageUriTemplate, the value is a page number. Otherwise it is a cursor that the integration layer returned in a page URI. Required when retrieving a page. See Pagination. |
Request body
None.
Response body
The response depends on the endpoint that the request addresses. A request to a collection returns a Collection. A request to a page returns a Page.
Example
An example request from a presentation layer:
GET /v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc
Host: example.org
This tells the integration layer that the presentation layer is searching for resources in the 'Masterpieces' collection that match the keyword 'rembrandt' and that matching resources must be ordered by relevance, descending, and then by value, ascending.
An example of the response of the integration layer:
{
"@context": "https://example.org/v1/context.json",
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc",
"type": "CuratedCollection",
"name": "Masterpieces",
"totalItems": 42,
"pageUriTemplate": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc{&page}",
"first": {
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=1",
"type": "Page",
"name": "Masterpieces: page 1",
"items": [
{
"id": "https://example.org/v1/entities/1234",
"type": "HeritageObject",
"name": "The Night Watch"
}
// Other items...
],
"next": {
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=2",
"type": "Page"
}
},
"last": {
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=3",
"type": "Page"
},
"partOf": {
"id": "https://example.org/v1/collections",
"type": "CuratedCollection",
"name": "Collections"
},
"capabilities": [
"https://specs.nde.nl/rest/v1/simple-search",
"https://specs.nde.nl/rest/v1/advanced-search",
"https://specs.nde.nl/rest/v1/facets",
"https://specs.nde.nl/rest/v1/suggestions"
],
"queryables": {
"id": "https://example.org/v1/collections/masterpieces/queryables"
}
}
The response indicates that the simple search has 42 results, that the collection includes its first page in first, and that the next page is page 2.
An example request from a presentation layer for a page in the same search:
GET /v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=2
Host: example.org
This tells the integration layer that the presentation layer is requesting page 2.
An example of the response of the integration layer:
{
"@context": "https://example.org/v1/context.json",
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=2",
"type": "Page",
"name": "Masterpieces: page 2",
"items": [
{
"id": "https://example.org/v1/entities/5678",
"type": "HeritageObject",
"name": "The Milkmaid"
}
// Other items...
],
"prev": {
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=1",
"type": "Page"
},
"next": {
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=3",
"type": "Page"
},
"partOf": {
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc",
"type": "CuratedCollection",
"name": "Masterpieces",
"totalItems": 42,
"pageUriTemplate": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc{&page}",
"first": {
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=1",
"type": "Page"
},
"last": {
"id": "https://example.org/v1/collections/masterpieces?q=rembrandt&orderBy=relevance:desc,value:asc&page=3",
"type": "Page"
}
}
}
The response indicates that this is page 2 of the simple search, with a previous page and a next page. Its partOf is the filtered collection.