External Search Service

External Search Service - Documentation for Developers

This note is intended to document certain features of the External Search Service (ESS) so that developers using the service can benefit from it. Developers maintaining ESS might want to have a look at the README.md file in the parent folder of this one.

The Basics

The production version of ESS is exposed at this URL:

http://ess-payara-service.os-externals.svc.cloud.dbc.dk/

There are two endpoints exposed, and both accept the same arguments, which will be listed below. The two endpoints are

http://ess-payara-service.os-externals.svc.cloud.dbc.dk/api/ and http://ess-payara-service.os-externals.svc.cloud.dbc.dk/api/rpn/

The only difference between them is that the one with rpn uses x-pquery as the parameter for the query when it calls MetaProxy - the other just uses query. The parameters you can send to the endpoints are:

• base (string): The base you wish to use for searching. Base here is meant as a MetaProxy (data)base.
• query (string): The query you wish to send.
• start (number): Send results back from a certain start point. Used for pagination, for example.
• rows (number): The number of rows you wish to return.
• format (string): The format you want the result in.
• trackingId: a string you can send if you wish to foloow your request in the servers' logs. This has no influence on the search result.

The service essentially calls Metaproxy (with a GET request) with the query and base from the request and then uses the OpenFormat service to format the response from Metaproxy before the response is sent back to the user/consumer of the service.

The base parameter is restricted by a set of options, specified in the service's environment variables. Therefore, the only allowed values for this parameter are bibsys, OLUCWorldCat, and ArticleFirst. If more bases are required, that is a change in the service (not necessarily a big one) that requires code and/or configuration changes.

The format parameter is restricted to a hardcoded list in the html-based user interface (there is a user story on that), but there are no restrictions imposed by the ESS service. Of course, the format should be acknowledged by the OpenFormat service. See below for a list of format currently supported by the OpenFormat service.

The service is a REST service, and there will be a response sent back to the caller. So if you are a perl programmer, you do not have to wait and check if a response is available or anything like that.

List of Supported Formats

Here is a list of the format strings that OpenFormat (and thereby ESS) accepts.

• bibdkWorkDisplay
• netpunkt_brief
• netpunkt_standard
• netpunkt_dm2
• netpunkt_marc21
• netpunkt_emne
• netpunkt_ess
• kb_marc21
• matvurd_standard
• bob_detail
• refWorks
• ris

An Example

Here is a URL that invokes the external search service:

http://ess-payara-service.os-externals.svc.cloud.dbc.dk/api/?base=OLUCWorldCat&query=asterix&start=1&rows=10&format=netpunkt_marc21&trackingId=dummytrackingId-42

Search Possibilities

We have been asked to provide some documentation on how the different bases can be searched. ESS simply forwards whatever query it is given to the MetaProxy service. Below are some examples of how it is possible to search.

All databases

• Comparison symbols are not supported. If this is needed, then that needs to be developed (and it needs to be investigated how MetaProxy handles that).
• The boolean operators AND and OR are supported. There is no support for negation.

Bibsys

• These search codes can be used:
  • dc.creator
  • dc.title
  • dc.subject
  • bath.isbn
  • bath.issn
  • dc.date
  • dc.language

WorldCat

• These search codes can be used:
  • dc.creator
  • dc.title
  • dc.subject
  • dc.language
  • bath.isbn
  • bath.issn
  • bath.id

ArticleFirst

• These search codes can be used:
  • dc.creator
  • dc.title
  • dc.date