Ga naar hoofdinhoud

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.

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​

NameData typeCardinalityDescription
versionstring1The version of the API. Example: v1.
...collectionsstring1 or moreThe path identifier(s) of the context collection. Example: collections/objects.

Query parameters​

NameData typeCardinalityDescription
qstring0 or 1A keyword query for filtering the items. The integration layer defines the minimum and maximum length and how the query is matched.
orderBystring0 or 1The 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).
sizenumber0 or 1The maximum number of items to retrieve. The minimum is 1. The integration layer defines the maximum.
pagestring0 or 1The 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.