TMW-API Documentation API-Version: 1.0.2

Version 2017-11-21

Index

For simple help, see here.

The main script for all api calls is data.php in the api root directory. The help file and documentation can be accessed via the doc.php by adding the parameter = {docFile.html}

HTML Parameters

The api can directly accessed without url rewrite. If the domain or format is left out, the default values, set in the config.ini, are used instead. The following parameters can be used:

domain

The domain defines the data type to retrieve. There are four types of data:

Due to the different content of each domain there are different fields of content returned.

format

The format parameter defines the data type returned. There are four types of formates:

Every domain data can be formatted in these formats.

language

The language defines the data language to be returned.

pos

The position parameter is an option value used in result lists to retreave a specific record. When using a image format (thumb, preview, download) it is possible to select the image out of a list.

processor

The processor parameter defines the preprocesser to be called before the data is sent to the format transformation.

query

The query parameter contains the query string sent to the SolR api. It has to obey the rules of the SolR api.

start

The record number in a search list to start from.

limit

The number of records to be returned. If no limit paramater is given, a miximum of 10 records is returned.

filter

A predifined filter added to the query.

Examples

	retrievel of object details:
	api/data.php?=object&=id:2938457

	search with format definition:
	api/data.php?=object&=resolve&=object_name:Dampflok* AND title:*k.k.St.B.*&=xml

	search in thesaurus:
	api/data.php?=thesaurus&=term:keyboard
	

URL rewrite

It is recommended to use the following url-rewrite rules on the webserver, due to the fact, that all inner links normally use this simple access method:

If a language code is used, the format parameter has to be present.

direct file access (css)
^api.*$
UNIX/LINUX $0
Windows {R:0}

Object by domain
^(.*)\.php?(.*)$
UNIX/LINUX /api/$1.php$2
Windows /api/{R:1}.php{R:2}

Processor
^([a-z]+)[\/]*(.*)$
UNIX/LINUX api/data.php?domain=$1&data=$2
Windows api/data.php?domain={R:1}&data={R:2}

No parameter (call help)
^[\/]*$
/api/doc.php?text=help.html

Documentation
^doc.php?(.*)$
UNIX/LINUX api/doc.php$1
Windows api/doc.php{R:1}

Config.ini

The configuration file contains the setup for the the api. It is separated in five sections:

[path]
; The global api path definitions
= "transform/" path to the transformation stylesheets
= "transform/images/" path to transformation images
[default]
; Default settings for format, domain and header
= "html" the html format allways should be defined for each domain
= "object" optional default domain
= "text/html" default http header
= "de" default language
[lang] list of supported languages
; supported languages
= "{language_code}"
...
international language code xx_yy
[format] list of valid format names
; List of defined output formats mapping to the xsl file names.
; For each domain the formats are stored in a directory named with the domain name.
; domain=object, format=rdf.xslt => object/rdf.xslt
= "{formatName}.xslt"
...
formats for data retrieval with corresponding xsl templates
[header] list of valid http headers
; List of http header definitions used by different formats
; the header name has to equal to the name defined for the format
; if no header ist defined for a format, the defaultHeader is used instead.
= "{http_header_string}"
...
header format definition for data output, i.e. application/xml, image/jpe.
[processor] list of automatic called preprocessors
; list of preprocessor plugins to be called before a optional http preprocessor
; this preprocessor plugins are called for each domain
; preprocessor plugin can support a parameter, separated by a . after the name
= "{processorName}[.{parameter}]"
...
[solr]
; The basic solr definitions
= "http://{domain}:8983/solr/"
[adlib]
; settings to use the adlib image handler for image retrieval
= "http://{adlibRoot}/adlibwebservice/wwwopac.ashx"
= "getcontent"
= "{adlib_server_name}"
= "{file_name_of_default_image}"
; list of domain definitions with the mapping to the solr core names
= "{SolR-core}"
...
mapping list between domain names and SolR core name
[{domain}.facets] list of defined facets. the facet is called using this name
; A list of facets for each domain. The name is created by the domain name with the postfix .facets.
= "{solr facet definition string}" i.e. facet.field=object

Preprocessor

See processor documentation

Facets

To use facets the solr facet string has to be defined in the config.ini for each domain. The group name in the ini-file is formed by the domain name and the .facets extension (object -> object.facets)

The following facets are defined in the config.ini:

The facet data is retrieved by adding the = {facet[,facet]} parameter to the search queue. As parameters a list of defined facets can be attached as a comma separated list. The parameter all returns all facet data definied in the config.ini file.

Format transformation

Stylesheets

The xsl-stylesheets for the data transformation are located in the transform directory. For each domain and each format one definition has to be present. For the html-format a html.css stylesheet should be used.

Feedback

The api offers a simple system to send store feedback to selected records.

The feedback preprocessor can be activated for different domains in the config.ini file. A feedback can be added by simply add the informations to the query and use the format feedback. To add a feedback there must be the attribute =add

The following fields can be added to the query string:

Some informations are added automatically: