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
frontend usage

Autocomplete in advanced search forms

facetvalues/:database/:field/:prefix

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

examples
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
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
    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
    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
    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
    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:

    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