Api Quick start

Introduction

The rkd api provides access to the rkd databases in solr, the thesauri in Adlib, and the fieldtags in the Rkd application.

Methods for querying the databases

autocomplete/:database/:field/:value

Autocomplete function on a field. Internally it is using the terms component in solr.

Options

• language [en|nl] If omitted, it will detect the language based on the request accept-language. 'nl' is default and doesn't need to be set.

examples

• /api/autocomplete/artists/materiaal/ver?language=nl Look in database `artists` in field `materiaal` for values starting with `ver`. Look in the language variant `nl` (default).

frontend usage

Autocomplete in advanced search forms

facetvalues/:database/:field/:prefix

Show a list of facets. See source code for more information

examples

• http://rkd.zend.picturae.pro/api/facetvalues/artists/materiaal/v?language=nl¶ms[baseUrl]=http%3A%2F%2Frkd.jos.picturae.pro¶ms[navUrl]=http%3A%2F%2Frkd.jos

frontend usage

This is used for the facetvalues popup when clicking on 'more' in the facet list.

instant/:database

Return instant search result. This method has only one option, `query`. Used for instant search results in the frontend.
NOTE: At this moment the instant search results are handled by the default per-database request handler. The solr config does have a per-database instant request hanlder, but it's use hasn't been implemented yet. This means that all options listed in method `search` can be used here, but this is not intended.

Options

• language [en|nl] If omitted, it will detect the language based on the request accept-language. 'nl' is default and doesn't need to be set.
• fieldset [brief|detail|minimal|searchlist] default:brief more about fieldsets

examples

• /api/instant/images?query=rembrandt&fieldset=searchlist

frontend usage

Instant results in `search in all databases`. Used fieldset is `searchlist`.

listdatabases

Returns a list of available databases in RKD Explore.
Note: Internally, `portraits` is not a database but a subset of `images`, (where field `isportrait` in `images` is `1`). Portraits has it's own request handler in solr.

examples

/api/listfieldsets/images

frontend usage

None

listfacets/:database

Returns a list of configured facets per database.
For each database the facets have been configured. The configuration can be found in the source code. It is in the fashion of a solarium facetset. When providing facet parameters as an option in -ie the search method, the facet parameters are merged with the configuration.
NOTE : This method doesn't reveal details about the facet configuration, like their type. This can be found in the source code (database configuration).

examples

/api/listfacets/images

frontend usage

None

listfields/:database

Returns a list of fields in a database,as it is configured in the source code.

Note: it doesn't reveal details about each field. Look in the source code.

examples

/api/listfields/images

frontend usage

None

listfieldsets/:database

Returns a list of available fieldsets per database and the fields they return.
For each database, a number of `fieldsets` have been configured. This defines which fields should be returned in the response. This doesn't affect which fields are searched.
Note: fieldset `detail` has no fields defined, it will return all fields in the database.

examples

/api/listfieldsets/images

frontend usage

None

record/:database/:id

Returns a single record. Parameter id is priref.

examples

• /api/artists/66219
• /api/artists/66219?format=json
• /api/artists/66219?language=en

frontend usage

For content in permalinks and direct links to detail records. Always in html format and requested server side.

search/:database

Search in a database. Main access point for the frontend. Returns json or html, depending on option `format` or on content-type of request. The results can be received in different fieldsets, which applies to json and html format. In fieldset `detail` results are always requested server side in html format. Other views can be requested in an ajax call in json format and rendered by javascript.

Options

• callback (string) Callback for jsonp
• facets (array) See listfacets, array is merged with value from configuration.
• fields (array) array with fields to retreive in resultset. When a fieldset is given, the fieldset fields override this parameter. BUG : because a default fieldset is set in the code, the `field` parameter doesn't affect anything.
• fieldset [brief|detail|minimal|searchlist] default:brief more about fieldsets
• filters (array) Filter query
• format [html|json]) If omitted, the format is detected in the content-type of the request
• language [en|nl] If omitted, it will detect the language based on the request accept-language. 'nl' is default and doesn't need to be set.
• params (array) Key/value pairs with parameters used in rendering the view. This is when the api has to know things about the frontend, for example a basepath to be able to create urls.
• query (string) Will be set as q parameter in request to solr
• rows (int) number of records to return
• sa (array) Advanced search parameters. Array of field/value pairs.
• sort (array) array with field/direction pairs
• start (int) start position of records to return
• usedefaultfacets (bool) default:true, more about facet configuration When set to false it will ignore the configuration. The facets defined in the request handlers are returned instead - not intended, but the way is works now.

examples

• /api/search/images?query=rembrandt&sort[priref]=asc
• /api/search/images?sa[naam_search]="Rembrandt van Rijn" Search for the literal value "Rembrandt van Rijn" in field `naam_search`. This is used in the advanced search forms.
• /api/search/library?filters[bibliographical_form]][]=Collectiecatalogus+[BV] Filter query, filtering on bibliographical_form=Collectiecatalogus+[BV]. The array notation `[bibliographical_form]][]` is only needed for multiple filters on the same field.
• /api/search/images?usedefaultfacets=false&format=json The default facets as defined in the database configuration are not used. If no other facets are set, the facets as defined in the request handler will be returned.
• api/search/images?filters[periode]=1799||1908&facets[periode][start]=1799&facets[periode][end]=1909&facets[periode][gap]=16&format=json
Search for images in periode 1799-1908 and add override the parameters `start`, `end` and `gap` from the configured facet `periode`.

frontend usage

For all simple and advanced searches.
Note: The frontend will do requests for detail pages always from the server, never from javascript, and always in html format. There are no mustache templates for detail view of records.
Note: The frontend is using an api call with fieldset=facets to retreive the facet list in html format (to show on the left side of the resultlist). This means that 2 api calls are done, one for the result list and one for the facet list.

searchform

Returns advanced search forms in html format.

examples

/api/searchform/images advanced search form for images

frontend usage

Frontend gets advanced search forms.

suggest/:database/:query

Returns suggested searches based on a search query term. Internally it uses the `did-you-mean` request handler.

examples

/api/suggest/images/rembra

frontend usage

`Did you mean` suggestions when a simple search query doesn't return results.

template

Returns a single template

examples

template/images?fieldset=brief Get brief template for images

frontend usage

none

templates

Returns Mustache templates for minimal, brief and searchlist views. (Searchlist is used in the instant search results in frontend). Detail views have no mustache templates, but are returned in html or json format.

examples

• /api/templates

frontend usage

The frontend loads the templates in the head. Search request in the result view are done with ajax, the response is in json. The template is rendered locally.

thesaurus[/:query]

Rkd has a number of thesauri, stored in adlib databases. They can be requested using an adlib Api. This api is not reachable for the world, the rkd api provedes a port to it. The following methods can be used. Returns html. For thesauri `exhibitions` and `auctions` links to related results in the databases are added.

:query (string/int) string value of term, or priref of term.

options

• callback (string) jsonp callback
• thesaurus (string) Name of thesaurus database (ie. `artthesaur`, `choiceiconclass` ). Default is `artthesaur`
• relTermUrl (string) Base url to build links to related terms.

examples

• http://rkd.zend.picturae.pro/api/thesaurus/16182?thesaurus=exhibitions

frontend usage

Thesaurus popups on clickable terms in detail view. The ajax calls in a detail page are done to the frontend, and the frontend does a server side call to the api.

Methods related to field labels an descriptions

For each field a label and description can be added, in multiple languages. These are stored in a mysql table (`fieldtags`) in the Rkd application. The fieldlabels and descriptions are used in the following places:

• A record's detail view. A Zend view helper is used to show them
• The advanced search forms
• The filter list

The frontend administrator section has an interface for editing these fieldlabels an descriptions. The frontend uses the api to store them. See also the FieldtagsController in the source code.

/fieldtags/:database[/:action][/:field]

parameters

• :database A rkd explore database. Note : portraits and images 2 different databases here (while they are not different in solr)
• :action [get|set|listfields] see source code for more information

examples

• api/fieldtags/artists/fieldlist