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:

http://visuallibrary.net/ihd/vlm/action/vlmTreeData?fragment=ContentsByState&os_type=ot_state&os_value=1

Ereignisse:

http://visuallibrary.net/ihd/vlm/action/vlmTimeline?eventtypes=Import&startts=2013-01-01&endts=2014-12-31

OAI¶

SRU¶

METS¶

Actions¶

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

http://visuallibrary.net/request/getNavIDs?row=0&col=deletedcount&table=datatype_summary

QS-Status „Bilder fehlen“

http://visuallibrary.net/request/getNavIDs?row=6&col=total&table=qsstate_summary

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¶

verb: ListIdentifiers, ListRecords, ListSets, ListMetadataFormats GetRecord, Identify
http://www.openarchives.org/

OAI¶

Liste aller freigegebenen Dokumente in einem bestimmt Format:

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

http://visuallibrary.net/s2wpihd/oai?verb=ListIdentifiers&metadataPrefix=mods

Abfrage von einzelnen Datensätzen mit bekanntem Identifier:

http://visuallibrary.net/oai?verb=GetRecord&metadataPrefix=db&identifier=3&mode=view

Liste aller Dokumentgruppen:

http://visuallibrary.net/oai?verb=ListSets

Eine bestimmte Dokumentgruppe:

http://visuallibrary.net/oai?verb=ListRecords&metadataPrefix=oai_dc&set=coll127227

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:

http://visuallibrary.net/oai/qs?verb=ListIdentifiers&metadataPrefix=mods

Liste aller Dokumente gefiltered nach qs-state=approved.

http://visuallibrary.net/oai/qs?verb=ListIdentifiers&metadataPrefix=mods&set=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