API and REST Interface for Programmers

The API-definition und REST interface can assist you in your work with dMGH, for example in:

• resolving abbreviations
• creating a direct link using the volume and page numbers
• citing charter editions according to the names of the rulers and the charter number

API Definition

get_API_version

This command provides you with the API version as a string. Each version number contains three elements divided by a dot. The first number indicates the main version. If the API changes significantly causing incompatibility with previous versions, the main version number will be raised. The second element designates the version number. This number will also be raised if the API has been significantly expanded. As long as the main version number remains the same, programmes working on the basis of older versions will still be functional. The third element changes whenever corrections or bugfixes have occurred without affecting the programme interface.

Programmes operating in production system should at least compare the main version number with the version number being used: If the main version number is higher than the version number your programme is using, there will probably be incompatibility.

The current API version is 0.2.0.

Please note that this version number refers only to the version of the API and its functionality. The underlying core modules and the database producing the results can be changed independent of the API version. This also applies for the documentation.

resolve

The command "resolve" selects a string as its argument and delivers a list of BSB numbers (= database IDs), each of which refers to a digitised MGH volume. Using this number, a link to the corresponding volume in dMGH could be created. However, the API already contains function calls to create links. Therefore it is advisable to use the API call to create links to ensure that the correct resource will be found if a link change occurs.

The resolve function searches the data collection in order to find as many volumes as possible. Exact hits are not privileged thereby. Thus, the search for „MGH SS 1“ would not only find "Scriptores in Folio 1", but also the volumes "Scriptores in Folio 10" through to "Scriptores in Folio 19", since these short titles also contain the string "MGH SS 1" (e.g. MGH SS 12). The function searches the fields „Kurztitel“ (the established abbreviated citations for MGH volumes, cfr. dMGH navigation tree), „Autor“ (surname, first name of the author), „Erscheinungsjahr“ (year of publication), and „Titel“ (title).

get_img_num

Arguments: BSB number and the page number.

This method goes directly to the image number of the specified volume (represented by the BSB number) and page (to be written exactly as in the printed book).

Using the BSB number and the image number, a link to the digitised copy of the specified page can be created. It is, however, advisable to use the API call to create links to ensure that the correct resource will be found if a link change occurs.

create_link

This command requires as its argument at least the BSB number. By adding the optional image number, a link to the specified page will be created.

REST interface

The interface query follows the REST guidelines. REST is the acronym for „Representational State Transfer.“ For information on the REST guidelines, see the Wikipedia article „Representational State Transfer“.

get_API_version ¶

resolve ¶

Note that all REST queries to the dMGH API may use strings containing special characters. These must be coded in UTF-8 format. Use the form below to create the correct codes.

get_img_num ¶

create_link ¶