APIs

Übersicht

VLS bietet verschiedene HTTP-APIs an. In der folgenden Tabelle sind die wichtigesten APIs beschrieben:

Name Auth Format Routing Consumer Source
VLM immer xml /vlm/action/NAME VLM-Client DB/Index
Act immer xml/json/plain /action/NAME Backend DB/Index
OAI opt xml /oai?command Harvester/DFG-Viewer DB
SRU opt xml /sru?query VLS-Suche Index
METS opt xml /mets/FMT/IDNAME/ID Debugging DB
RSS opt xml /rss/oai_dc Feedreader DB
IIIF opt json /i3f Thirdparty SPAs, UIX0 DB/Index
Filter opt json/xml /api/filter/NAME UIX DB/Index
S2W fehlt xml /s2w Technische Partner DB
OPDS opt xml /opds EB Reader DB/Index
DOWN opt binary /download/RES/ID Browser/Harvester DB/FS
Name Stabilität Protocol/Payload Protocol Payload
VLM mittel/schwach Alles Administration, Resourcen
Act schwach/schwach Alles Administration, Resourcen
OAI stark/mittel DT1-Listen/IDs OAI-Writer (mets, mods, mab, ..)
SRU stark/stark DT1-Listen/IDs SearchRetrieve (+Extensions)
METS stark/mittel IDs Metsbuilder (vd, capsule, domain, full, ..)
RSS stark/mittel DT1-Listen HTML + OAI-payloads
IIIF stark/mittel DT0-3 Frontend
Filter schwach/schwach Alles Frontend
S2W stark/stark Job-Listen/IDs Scanjobs DT1 und DT5
OPDS stark/stark DT1-Listen/IDs Collections + EPub/PDF Resourcen
DOWN mittel/stark IDs VFS-Resources, Archive und Webcache Images

Beispiele

VLM

Mit folgenden Routen lassen sich “Alle Inhalte” navigieren:

Folgende Routen ermitteln die Daten, die unter “Eigenschaften” angezeigt werden:

Routen für Statuswerte:

Ereignisse:

OAI

SRU

METS

Actions

Wenn Daten aus /qa/stats http://visuallibrary.net/qa/stats:

QS-Status “Bilder fehlen”

OAI

Das OAI-Protokoll bietet die Möglichkeit Listen von Metdatenknoten (datatype=1) in verschiedenen Formaten zu traversieren. In VLS können diese Listen nach Domain-, Kollektion-und Statuskriterien gebildet werden. Über die aus der VLID abgeleiteten OAI-Identifier lassen sich auch Einzelrecords ausliefern. Die Listen werden für inkrementelles Harvesting in offset/maximum-limitierten Paketen ausgeliefert.

Der HTTP-API Endpunkt in VLS ist /oai. Mit Hilfe eines Domainprefixes, lässt sich die OAI-Abfrage auf einen Domainkontext einschränken /DNAME/oai. Die Schnittstelle wird mit HTTP-GET Parametern angesteuert.

Parameter

OAI

Liste aller freigegebenen Dokumente in einem bestimmt Format:

Liste aller freigegebenen Dokumente (nur Identifier) in einer bestimmten Domain:

Abfrage von einzelnen Datensätzen mit bekanntem Identifier:

Liste aller Dokumentgruppen:

Eine bestimmte Dokumentgruppe:

Eine weitere Möglichkeit besteht darin die Auslieferung der Dokumente über andere Statuswerte als die Freigabe zu steuern. Dafür ist jedoch eine Authentifizierung notwendig:

Liste aller Dokumente mit Zeitstempel der qs-state Änderung:

Liste aller Dokumente gefiltered nach qs-state=approved.

S2W

<meta>

  • transportiert Fehlerinformationen
  • transportiert allgemeine Serverinformationen wie Version
  • was fehlt:
    • Client-Version, Authentifizierungsinformation

<data>

  • entweder Liste von Jobs (/getJobs) oder Einzeljob (/getJob)

/getJobs

  • &scanState=XXX Parameter um Listen von Jobs auf Statuswerte zu filtern (qs-state oder ESA/order-state)
    • order neue Aufträge im ESA-Mode oder Status “Auftrag erteilt” im Retro-Mode
    • rescan Aufträge im Status: Images fehlen/fehlerhaft
    • qsinprogress obsolete (alle die, die nicht gescanned werden sollen)
    • finished obsolete
  • Ausbaustufen: Priorisierung (Sortierung?) und Scannerauswahl
  • Navigationsinfos für /getJobs (total, max, offset) am <jobs offset="10" total=...>-Element

/getJob

  • /getJob addressiert immer via &identifier=XXX (Mediennummer in ce, VLID in esa, Katalognummer in Domaintyp retro)

<job>

  • Attribute von <job>
    • type: s2w-mode (wertet MDS nicht aus)
    • metadataID: VLID (verwendet MDS als uniquen Job-Identifier)
    • metadataDomain: Domainname (wertet MDS nicht aus)
    • metadataType: VL-Type (wertet MDS nicht aus)
    • metadataDisplay: VL-Type übersetzt in String (zeigt MDS zur Info an)
    • identifier: Katalognummer
    • fsPath: Zielverzeichnis im FTP/Samba-Root normalerweise Domainname
    • fsName: Zielverzeichnis unter fsPath, Katalognummer oder VLID
    • dateIssued: Erscheinungsjahr (zeigt MDS zur Info an)
    • qsState: Übersetzung des qs-State (Bilder Fehlerhaft, …) (zeigt MDS zur Info an)
    • qsComment: Kommentar zum qs-State (zeigt MDS zur Info an) (TODO: umbennen zu comment)
    • orderComment: Kommentar zum order-State (nur ESA) (zeigt MDS zur Info an) (TODO: umbennen zu comment)
    • scanState: Scanbehavior am qs/order-state (Rückrichtung /getJobs?scanState=XXX) (wertet MDS aus, erzeugt z.B. “/HT_NUMMER/Nachscans” Folder)
    • obsolete: metadataDeliveryDate, isOrder (durch type=esa), wfState, wfComment
  • Elemente von <job>

Periodicals:

/s2w/createPeriodicalStructure?type={tome|year}&parent=123&label=LABEL

<response>
    <meta/>
    <data>
        <node vlid="567"/>
    </data>
</response>

Fehlerfälle:

  • duplicate labels
  • unknown parent, unknown type

/s2w/getJob?identifier=HT0000

<job type="periodical">
    <identifier vlid="666" sysnum="HT0000">
    <export fsPath="domain1" fsName="HT0000">
    <types>
    <periodical>
        <node label="Band 1" vlid="999">
            <node vlid="123" label="Jg. 1848" status="finished"/>
            <node vlid="456" label="Jg. 1849" status="finished"/>
        </node>
        <node label="Band 2" vlid="1000">
            <node vlid="1230" label="Jg. 1850" status="finished"/>
            <node vlid="4560" label="Jg. 1851" status="finished"/>
        </node>
    </periodical>
</job>

Export:

/domain1/HT0000/123
  /Heft_1
  /Beilage_1

/s2w/getJobs?scanState=rescan

<job>
    <identifier vlid="666" catalognum="HT0000">
    <export fsPath="domain1" fsName="HT0000">
    <status >
    <periodical>
        <node label="Band 1" vlid="999">
            <node vlid="123" label="Jg. 1848">
                <node vlid="789" label="Heft 1" status="rescan" comment="Seite 1-3 fehlt"
            <node>
        </node>
    </periodical>
</job>

Export:

/domain1/HT0000/789
    /Nachscans