TMW-API Documentation API-Version: 1.0.2

Version 2020-12-05

Index

HTML Parameters
domain
format
language
pos
processor
query
start
limit
filter
URL rewrite
Config.ini
Preprocessor
Facets
Format transformation
Stylesheets
Feedback

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 text= {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?domain=object&query=id:2938457

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

	search in thesaurus:
	api/data.php?domain=thesaurus&query=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)
regexp		^api.*$
rewrite	UNIX/LINUX	$0
	Windows	{R:0}

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

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

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

Documentation
regexp		^doc.php?(.*)$
rewrite	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 -> api system path definitions
api -> global api parameters
format -> valid api format definitions
solt -> SolR path and core definitions
facet -> global facet parameters
facets -> facet definition for each core

[path]

; The global api path definitions

xsl = "transform/" path to the transformation stylesheets

image = "transform/images/" path to transformation images

[default]

; Default settings for format, domain and header

defaultFormat = "html" the html format allways should be defined for each domain

defaultDomain = "object" optional default domain

defaultHeader = "text/html" default http header

defaultLanguage = "de" default language

[lang] list of supported languages

; supported languages

{languageName} = "{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} = "{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.

{formatName} = "{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

{domain}[] = "{processorName}[.{parameter}]"
...

[solr]

; The basic solr definitions

url = "http://{domain}:8983/solr/"

[adlib]

; settings to use the adlib image handler for image retrieval

adlibUrl = "https://{adlibRoot}/adlibwebservice/wwwopac.ashx"

command = "getcontent"

server = "{adlib_server_name}"

defaultImage = "{file_name_of_default_image}"

; list of domain definitions with the mapping to the solr core names

{domain} = "{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.

facetName = "{solr facet definition string}" i.e. facet.field=object

Preprocessor

See processor documentation

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[,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 command=add

The following fields can be added to the query string:

type feedback type (i.e. feedback, debug, missing keywords,...)
category feedback category (i.e. knowlage, image request, load request,...)
email A email address to contact the feedback author
text Feedback text string

Some informations are added automatically:

date Datetime of the entry
query Search query from which the feedback is triggered
ip IP of the sending user

[path]
; The global api path definitions
xsl = "transform/"	path to the transformation stylesheets
image = "transform/images/"	path to transformation images
[default]
; Default settings for format, domain and header
defaultFormat = "html"	the html format allways should be defined for each domain
defaultDomain = "object"	optional default domain
defaultHeader = "text/html"	default http header
defaultLanguage = "de"	default language
[lang]	list of supported languages
; supported languages
{languageName} = "{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} = "{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.
{formatName} = "{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
{domain}[] = "{processorName}[.{parameter}]" ...
[solr]
; The basic solr definitions
url = "http://{domain}:8983/solr/"
[adlib]
; settings to use the adlib image handler for image retrieval
adlibUrl = "https://{adlibRoot}/adlibwebservice/wwwopac.ashx"
command = "getcontent"
server = "{adlib_server_name}"
defaultImage = "{file_name_of_default_image}"
; list of domain definitions with the mapping to the solr core names
{domain} = "{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.
facetName = "{solr facet definition string}"	i.e. facet.field=object