☰
Kivikese tutvustus
Arhiivide tutvustus
Kivikese tegijad
Terminid
Otsinguabi
ID-kaardi abi
Arvandmed
Avaandmed
Juurdepääs ja koopiate tellimine
Vabatahtlik kaastöö
ERA märksõnastik
Privaatsuspoliitika
Kivike SOAP API 1/8 07.12.2011
 
Kivikese API – SOAP liides

SOAP liides asub aadressil: http://kivike.kirmus.ee/soap.php
Kivikese SOAP liides võimaldab teha Kivikesse päringuid ja saada vastuseid SOAPsõnumitena.
Realiseeritud on kolm päringut:
1) Lihtotsing otsingusõna järgi
2) Metaandmete küsimine arhivaali PID-i järgi
3) Faili URLi küsimine PID-i järgi

SOAP-sõnumite kirjeldused

Sõnumites kasutatakse andmestruktuurina ühe- või mitmetasemelisi massiive, kus andmed
antakse key-value paaridena. Seda nii päringutes kui ka vastustes.

Lihtotsingu päring

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:examples:kirjandusmuuseum"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAPENC="
http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:ns3="http://example.org/schema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body>
<ns1:getSearch>
<request SOAP-ENC:arrayType="xsd:anyType[][1]" xsi:type="ns3:anyTypeArray2">
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">keyword</key>
<value xsi:type="xsd:string">hurt</value>
</item>
</item>
</request>
</ns1:getSearch>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Võtmeväärtus “keyword” on fikseeritud osa päringust, samas kui väärtus “hurt” on
otsingusõna. Otsingusõna võib koosneda ka mitmest sõnast, nt. “jakob hurt”. Otsing on
realiseeritud sarnaselt lihtotsinguga Kivikese avalehel. Rakenduvad ka juurdepääsupiirangud.
(Andmebaasi poole pealt kasutatakse ASA full text search contains päringut).

Lihtotsingu vastus

Päringu vastusena tagastatakse nimekiri leitud säilikutest. Säilikute koguarv on piiratud
(hetkel on piirang 500 säilikut). Iga säiliku puhul on välja toodud säiliku viide, nimi ja PID.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
Kivike SOAP API 2/8 07.12.2011
xmlns:ns1="urn:examples:kirjandusmuuseum"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAPENC="
http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:ns3="http://example.org/schema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getSearchResponse>
<response SOAP-ENC:arrayType="xsd:anyType[][62]" xsi:type="ns3:anyTypeArray2">
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">name</key>
<value xsi:type="xsd:string">Test säilik 1</value>
</item>
<item>
<key xsi:type="xsd:string">reference</key>
<value xsi:type="xsd:string">H 1 22</value>
</item>
<item>
<key xsi:type="xsd:string">pid</key>
<value xsi:type="xsd:string">ERA-11234-60995-49084</value>
</item>
</item>
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">name</key>
<value xsi:type="xsd:string">Test säilik 2</value>
</item>
<item>
<key xsi:type="xsd:string">reference</key>
<value xsi:type="xsd:string">H 11 03</value>
</item>
<item>
<key xsi:type="xsd:string">pid</key>
<value xsi:type="xsd:string">ERA-10349-39767-83852</value>
</item>
</item>
...
</response>
</ns1:getSearchResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Kui otsingu tulemusena säilikuid ei leita, tagastatakse tühi massiiv.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:examples:kirjandusmuuseum"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://example.org/schema" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAPENV:
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getSearchResponse>
<response xsi:nil="true" xsi:type="ns2:anyTypeArray2"/>
</ns1:getSearchResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>


Metaandmete küsimise päring
PID-i alusel saab küsida ühe säiliku (arhivaali) metaandmeid.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:examples:kirjandusmuuseum"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAPENC="
http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:ns3="http://example.org/schema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getData>
<request SOAP-ENC:arrayType="xsd:anyType[][1]" xsi:type="ns3:anyTypeArray2">
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">pid</key>
<value xsi:type="xsd:string">ERA-11012-61463-48246</value>
</item>
</item>
</request>
</ns1:getData>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Metaandmete küsimise vastus

Metaandmete küsimise vastuseks antakse arhivaali metaandmed ning alamosad (subparts): säiliku puhul näiteks esitused, esituse puhul failid. Alamosade kohta tuuakse ära põhiandmed: nimi, viide, pid, registreerimisaeg, liik ja alamliik. Ülejäänud alamosade metaandmed tuleb küsida järgmise päringuga alamosa PID-i järgi. Alamosade kohta tuuakse ka välja omakorda nende alamosad, seega saab säiliku metaandmeid küsides teada ka säiliku failid (ja kõik muud säilikuga seotud alamarhivaalid). Metaandmetele ja alamosadele rakenduvad juurdepääsupiirangud.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:examples:kirjandusmuuseum"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAPENC="
http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:ns3="http://example.org/schema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getDataResponse>
<response SOAP-ENC:arrayType="xsd:anyType[][1]" xsi:type="ns3:anyTypeArray2">
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">meta</key>
<value xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">name</key>
<value xsi:type="xsd:string">H 2 17</value>
</item>
<item>
<key xsi:type="xsd:string">reference</key>
<value xsi:type="xsd:string">H 2 17</value>
</item>
<item>
<key xsi:type="xsd:string">pid</key>
<value xsi:type="xsd:string">ERA-11012-61463-48246</value>
</item>
<item>
<key xsi:type="xsd:string">created</key>
<value xsi:type="xsd:string">2011-01-13 17:03:45.355</value>
</item>
<item>
<key xsi:type="xsd:string">type</key>
<value xsi:type="xsd:string">Säilik</value>
</item>
<item>
<key xsi:type="xsd:string">subtype</key>
<value xsi:type="xsd:string">Käsikiri</value>
</item>
<item>
<key xsi:type="xsd:string">metadata</key>
<value xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">Nimi</key>
<value xsi:type="xsd:string">H 2 17</value>
</item>
<item>
<key xsi:type="xsd:string">Asutus</key>
<value xsi:type="xsd:string">Eesti Kirjandusmuuseum</value>
</item>
<item>
<key xsi:type="xsd:string">Allüksus</key>
<value xsi:type="xsd:string">Eesti Rahvaluule Arhiiv</value>
</item>
<item>
<key xsi:type="xsd:string">Viide</key>
<value xsi:type="xsd:string">H 2 17</value>
</item>
<item>
<key xsi:type="xsd:string">Ajakate</key>
<value xsi:type="xsd:string">1860-1907</value>
</item>
<item>
<key xsi:type="xsd:string">Keel</key>
<value xsi:type="xsd:string">et</value>
</item>
<item>
<key xsi:type="xsd:string">Märksõna</key>
<value xsi:type="xsd:string">folklore</value>
</item>
</value>
</item>
</value>
</item>
<item>
<key xsi:type="xsd:string">subparts</key>
<value SOAP-ENC:arrayType="ns2:Map[2]" xsi:type="SOAP-ENC:Array">
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">meta</key>
<value xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">name</key>
<value xsi:type="xsd:string">PDF Esitus</value>
Kivike SOAP API 5/8 07.12.2011
</item>
<item>
<key xsi:type="xsd:string">reference</key>
<value xsi:type="xsd:string">H 2 17</value>
</item>
<item>
<key xsi:type="xsd:string">pid</key>
<value xsi:type="xsd:string">ERA-11012-61480-96179</value>
</item>
<item>
<key xsi:type="xsd:string">created</key>
<value xsi:type="xsd:string">2011-01-13 17:04:10.150</value>
</item>
<item>
<key xsi:type="xsd:string">type</key>
<value xsi:type="xsd:string">Esitus</value>
</item>
<item>
<key xsi:type="xsd:string">subtype</key>
<value xsi:type="xsd:string">Kasutuskoopia</value>
</item>
</value>
</item>
<item>
<key xsi:type="xsd:string">subparts</key>
<value SOAP-ENC:arrayType="ns2:Map[4]" xsi:type="SOAP-ENC:Array">
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">meta</key>
<value xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">name</key>
<value xsi:type="xsd:string">test_1_01.pdf</value>
</item>
<item>
<key xsi:type="xsd:string">reference</key>
<value xsi:type="xsd:string">H 2 17</value>
</item>
<item>
<key xsi:type="xsd:string">pid</key>
<value xsi:type="xsd:string">ERA-11012-61488-98041
</value>
</item>
<item>
<key xsi:type="xsd:string">created</key>
<value xsi:type="xsd:string">2011-01-13 17:04:10.336
</value>
</item>
<item>
<key xsi:type="xsd:string">type</key>
<value xsi:type="xsd:string">Fail</value>
</item>
<item>
<key xsi:type="xsd:string">subtype</key>
<value xsi:type="xsd:string">Tekstifail</value>
</item>
</value>
</item>
<item>
<key xsi:type="xsd:string">subparts</key>
<value xsi:nil="true"/>
</item>
Kivike SOAP API 6/8 07.12.2011
</item>
</value>
</item>
</item>
</value>
</item>
</item>
</response>
</ns1:getDataResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Kui PID-le ei vasta ühtegi arhivaali või pole arhivaalile ligipääs lubatud, siis on vastuseks tühi massiiv.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:kivike:kirjandusmuuseum" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:ns2="http://example.org/schema"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAPENC="
http://schemas.xmlsoap.org/soap/encoding/" SOAPENV:
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getDataResponse>
<response xsi:nil="true" xsi:type="ns2:anyTypeArray2"/>
</ns1:getDataResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Faili URLi küsimise päring
Antud päringuga saab PID-i järgi küsida faili URL-i. URL tagastatakse juhul, kui PID-le
vastab fail ning juurdepääsupiirangud ei tõkesta faili vaatamist.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:examples:kirjandusmuuseum"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAPENC="
http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:ns3="http://example.org/schema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getUrl>
<request SOAP-ENC:arrayType="xsd:anyType[][1]" xsi:type="ns3:anyTypeArray2">
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">pid</key>
<value xsi:type="xsd:string">ERA-11012-61488-98041</value>
</item>
</item>
</request>
</ns1:getUrl>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Faili URLi küsimise vastus
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:examples:kirjandusmuuseum"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAPENC="
http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:ns3="http://example.org/schema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getUrlResponse>
<response SOAP-ENC:arrayType="xsd:anyType[][1]" xsi:type="ns3:anyTypeArray2">
<item xsi:type="ns2:Map">
<item>
<key xsi:type="xsd:string">url</key>
<value xsi:type="xsd:string">http://kivike.kirmus.ee/ERA-11012-
61488-98041
</value>
</item>
</item>
</response>
</ns1:getUrlResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Kui faili ei ole või fail on juurdepääsupiirangutega kaitstud, on tulemuseks tühi massiiv:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="urn:kivike:kirjandusmuuseum"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://example.org/schema"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAPENC="
http://schemas.xmlsoap.org/soap/encoding/" SOAPENV:
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:getDataResponse>
<response xsi:nil="true" xsi:type="ns2:anyTypeArray2"/>
</ns1:getDataResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Võtmeväärtused päringutes
Päringutes on kasutusel järgmised fikseeritud võtmed:

Võti: Päring(ud): Selgitus
keyword getSearch otsingusõna
name getSearchResponse, getDataResponse arhivaali nimi
reference getSearchResponse, getDataResponse arhivaali viide
pid getSearchResponse, getData,
getDataResponse, getUrl
arhivaali unikaalne
püsiidentifikaator
meta getDataResponse arhivaali metaandmete blokk
created getDataResponse arhivaali süsteemis
registreerimise aeg
type getDataResponse arhivaali liik: säilik, fail, jt.
subtype getDataResponse arhivaali alamliik: käsikiri,
foto, pildifail, jt.
metadata getDataResponse arhivaali tunnuste blokk (tunnused
on arhivaalidel erinevad ja nende
võtmed pole fikseeritud ning
võivad muutuda)
subparts getDataResponse arhivaali alamarhivaalid: säiliku
puhul esitused, failid, palad, jt.
url getUrlResponse püsilink failile

Lisaks neile on metaandmete küsimise vastuses (getDataResponse) elemendi metadata all kasutatud eestikeelseid võtmeid (Nimi, Asutus, Allüksus, Viide, Ajakate, Keel, Märksõna). Need on tunnuste nimed Kivikese süsteemis, mis ei ole fikseeritud ning võivad aja jooksul muutuda ja lisanduda. Erinevatel arhivaalidel võivad olla erinevad tunnused, seega on ka päringu vastuses erinevad võtmed.


Eesti Kirjandusmuuseum