Kirjastohakemiston rajapinta v2

Johdanto

Tämä dokumentti kuvaa Kirjastot.fi:n kirjastohakemiston julkisen rest-rajapinnan. Rajapinta mahdollistaa kirjastojen tietojen käytön kolmannen osapuolen sovelluksissa. Rajapinnan versio 2.0 korvaa vanhan rajapinnan 1.0, jota ei enää kehitetä. Vanha rajapinta on kuitenkin käytettävissä vielä toistaiseksi. Vanhan dokumentaation löytää osoitteesta http://api.kirjastot.fi/v1-doc.html.

Yleistä rajapinnasta

Rajapintaa käytetään tavallisilla http-pyynnöillä, joihin vastataan asiakassovelluksen määrittämällä datatyypillä. Tuetut datatyypit ovat xml, json ja jsonp. Asiakas tekee pyynnöt tavallisina http:n get-pyyntöinä.

Rajapinta on kaikille avoin eikä vaadi asiakasohjelmien tai käyttäjien tunnistautumista. Asiakassovellukset voivat halutessaan "ilmoittaa olemassaolostaan" käyttämällä urlissa parametria client, jolle annetaan arvoksi sovelluksen nimi ja versio (client=kifisovellus/1.0).

Rajapinnan käytön havainnollistamiseksi on tehty muutamia esimerkkisovelluksia: http://api.kirjastot.fi/widgets/demo.php

Demon lähdekoodit ovat saatavilla Kirjastot.fi:n GitHub-sivulta: https://github.com/libraries-fi/library-directory-api-demo

Vastauksen tietotyypin määrittäminen

Asiakas voi määrittää tuloksen tietotyypin käyttämällä http-protokollan Accept-otsikkotietoa, jonka voi ylikirjoittaa get-parametrilla format. Accept-otsikossa määritetään haluttu muoto käyttämällä standardia mime-tyyppiä. Format-parametrin arvona käytetään ns. tiedostopäätettä. Mikäli otsikkotiedoissa määritellään useampi tyyppi, valitaan http-standardin mukaisesti korkeimman prioriteetin omaava tyyppi.

Jsonp-muotoa käyttäessä täytyy myös määrittää ns. callback-funktion nimi get-parametrilla callback.

Palautettavan datan merkistö on utf8. Json-muotoisissa dokumenteissa ascii-taulun ulkopuoliset merkit on enkoodattu json-standardin mukaisesti.

Rajapinnan kutsut

Rajapinnan kutsujen polut myötäilevät rest-filosofiaa. Polussa määritetään haettavan resurssin tyyppi sekä mahdollinen tietueen tunniste. Muut parametrit määritellään urlin query string -osassa.

Kutsujen muoto on seuraavanlainen:

http://api.kirjastot.fi/v2/:resurssi/:id?parametrit
http://api.kirjastot.fi/v2/search/:resurssi?parametrit

Tässä :resurssi tarkoittaa resurssin tyyppiä ja :id resurssin tunnistetta. Kysymysmerkin jälkeinen osa (_parametrit_) on tavallinen query string. Resurssin tyyppi voi olla moniosainen, esimerkiksi libraries/services. Jälkimmäistä kutsua käytetään tietueiden massahakuun.

Kutsuilla on joitakin yhteisiä parametreja, joiden merkitys ja vaikutus on kaikille tietotyypeille sama:

Kutsujen listaus

Polkuun upotetut parametrit on merkitty kaksoispisteellä, esim ":id".

Lisää hakuehdoista

Hakuehtoja on mahdollista monipuolistaa käyttämällä operaattoreita ! (not), * (or), < (less or equal) ja > (larger or equal). Lisäksi vapaatekstikentissä voidaan käyttää jokerimerkkinä asteriskia *. Jos halutaan hakea kahden eri kentän perusteella siten, että vain toisen ehdon tarvitsee toteutua, kenttien nimien perään voidaan liittää asteriski *. Yksittäisen kentän vaihtoehtoistamiseksi eri arvot erotellaan pilkuin. Numeerisia kenttiä sekä päivämääräkenttiä voidaan vastaavasti rajata arvovälille operaattoreilla < ja >.

Ehdollistaminen toimii siten, että tietue hyväksytään tulokseen, mikäli se täsmää vähintään yhteen vaihtoehtoiseen hakuehtoon. Lisäksi kyseisen tietueen täytyy täsmätä kaikkiin pakollisiin hakuehtoihin (joko negaatiot tai tavalliset ehdot).

Teknisiä rajoituksia

Yksi hakuavain eli kentän nimen ja mahdollisen operaattorin yhdistelmä voi esiintyä urlissa enintään yhden kerran. Ei siis ole mahdollista hakea sekä ehdolla city*=helsinki että city*=vantaa, vaan nämä täytyy yhdistää muotoon city=helsinki,vantaa. Haussa on mahdollista käyttää saman kentän kahta eri variaatiota, esimerkiksi avaimia city* ja city- tai city ja city-.

Sanahaut eivät ole ns. case-sensitive eli eivät tee eroa isojen ja pienten kirjaimien välille.

Esimerkkejä

Kyselyiden muuntaminen Boolen logiikaksi

?city=helsinki&consortium=helmet&name-=foo*
city=helsinki AND consortium=helmet NOT name=foo*

?city*=helsinki,vantaa,espoo&name*=foo
city=helsinki OR city=vantaa OR city=espoo OR name=foo

?city*=vantaa&name=foo*&geo*=20,30&city-=helsinki
name=foo* NOT city=helsinki AND (city=vantaa OR geo=20,30)

Kyselyitä

Haetaan kaikki kirjastot, jotka sijaitsevat joko Helsingissä tai Vantaalla: http://api.kirjastot.fi/v2/search/libraries?city=helsinki,vantaa

Haetaan kaikki Helmet-kimpan kirjastot, jotka eivät sijaitse Helsingissä: http://api.kirjastot.fi/v2/search/libraries?consortium=helmet&city-=helsinki

Haetaan kirjastoja joko Vantaalta tai Aalto-kimpasta: http://api.kirjastot.fi/v2/search/libraries?city*=vantaa&consortium*=aalto

Haetaan Helmet-kimpan kirjastot, joita on muokattu vuoden 2013 aikana. http://api.kirjastot.fi/v2/search/libraries?consortium=helmet&modified>=2013-01-01

Yksittäisen kirjaston tiedot

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/libraries/:id?parametrit

Tuloksena palautetaan koko kirjaston tietue.

Sallitut parametrit

Palautettavien tietojen laajuus – with

Koska kirjastojen tietueissa on hyvin paljon tietoa, voidaan esimerkiksi tiedonsiirron optimoimiseksi suotia pois tietueiden tarpeettomia osioita with-parametria käyttäen. Parametrille annetaan arvoksi pilkuilla erotettu lista niistä osioista, jotka halutaan sisällyttää mukaan tietueeseen.

Sallitut arvot

Henkilöstön listaus

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/libraries/staff/:id?parametrit

Sallitut parametrit

<collection count="1">
    <person>
        <id>ga2w-WoVTI-31o4Ia12BDA</id>
        <name>
            <first>Maisa</first>
            <last>Malli</last>
        </name>
        <email>maisa.malli@kirjastot.fi</email>
        <telephone>+358551234567</telephone>
        <modified>2013-01-01T12:00</modified>
        <job_title multilang="true">
            <value lang="fi">Kirjastonjohtaja</value>
            <value lang="sv"/>
            <value lang="en"/>
            <value lang="se"/>
        </job_title>
        <responsibility multilang="true">
            <value lang="fi">Kirjaston johtaminen</value>
            <value lang="sv"></value>
            <value lang="en"></value>
            <value lang="se"></value>
        </responsibility>
        <url multilang="true">
            <value lang="fi"></value>
            <value lang="sv"></value>
            <value lang="en"></value>
            <value lang="se"></value>
        </url>
        <organisations>
            <organisation is_head="1">goQMRZg5vsamxx4fbj-A</organisation>
        </organisations>
    </person>
</collection>

Aikataulujen listaus

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/libraries/schedules/:id?parametrit

Tuloksena palautetaan määrätyn kirjaston aikataulutiedot haetulla aikavälillä.

Sallitut parametrit

Kun date- tai week-parametria käytetään operaattoreiden < ja > kanssa, täytyy määrittää sekä alku- että loppuarvo!

<collection count="3">
    <day number="1">
        <date>2013-05-20</date>
        <opens>09:00</opens>
        <closes>20:00</closes>
    </day>
    <day number="2">
        <date>2013-05-21</date>
        <opens>09:00</opens>
        <closes>20:00</closes>
    </day>
    <day number="3">
        <date>2013-05-22</date>
        <opens>09:00</opens>
        <closes>20:00</closes>
    </day>
</collection>

Palveluiden listaus

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/libraries/services/:id?parametrit

Tuloksena palautetaan lista kirjastoon liitetyistä palveluista.

Sallitut parametrit

<collection count="1">
    <service>
        <type>tila</type>
        <price>0</price>
        <for_loan>1</for_loan>
        <description></description>
        <modified>2013-05-30T15:15:34</modified>
        <tags>
            <item>ensimmäinen tagi</item>
            <item>toinen tagi</item>
        </tags>
        <contact>
            <telephone></telephone>
            <email></email>
            <url multilang="true">
                <value lang="fi"></value>
                <value lang="sv"></value>
                <value lang="en"></value>
                <value lang="se"></value>
            </url>
        </contact>
        <name multilang="true">
            <value lang="fi">Palvelun nimi</value>
            <value lang="sv"></value>
            <value lang="en"></value>
            <value lang="se"></value>
        </name>
        <picture>
            <file size="small">http://kirkanta.kirjastot.fi/media/image_content/small/2560x1600-51a74017.jpeg</file>
            <file size="medium">http://kirkanta.kirjastot.fi/media/image_content/medium/2560x1600-51a74017.jpeg</file>
            <file size="large">http://kirkanta.kirjastot.fi/media/image_content/large/2560x1600-51a74017.jpeg</file>
            <file size="huge">http://kirkanta.kirjastot.fi/media/image_content/huge/2560x1600-51a74017.jpeg</file>
        </picture>
        <template>
            <id>1n6Ln1SdTaGJ6v1T-yFfkQ</id>
            <name multilang="true">
                <value lang="fi">Jaetun mallipalvelun nimi</value>
                <value lang="sv"></value>
                <value lang="en"></value>
                <value lang="se"></value>
            </name>
        </template>
    </service>
</collection>

Yksittäisen kirjastoauton pysäkin tiedot

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/mobilestops/:id?parametrit

Tuloksena kirjastoauton pysäkin tietue.

Yksittäisen osaston tiedot

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/mobilestops/:id?parametrit

Tuloksena kirjastoauton pysäkin tietue.

Sallitut parametrit

Kirjastojen massahaku

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/search/libraries?parametrit

Tuloksena palautetaan lista kirjastojen tietueista.

<collection count="3">
    <library>...</library>
    <library>...</library>
    <library>...</library>
</collection>

Sallitut parametrit

Koordinaattihaku – geo

Kirjastoja voi hakea käyttäjän maantieteellisen sijainnin perusteella käyttämällä koordinaattihakua. Koordinaateilla haettaessa koordinaatit määritetään geo-parametrilla. Sen arvo on koordinaattipari x,y (esim. geo=30.12,45.77), joka ilmaisee sijainnin eli pisteen, jonka läheisyydestä kirjastoja haetaan. Oletusarvoisesti kirjastoja haetaan 10 km:n säteeltä, mutta etäisyyden voi määrittää parametrilla distance, jolle annetaan etäisyys metreissä (esim. distance=10000).

Kirjastojen aikataulujen massahaku

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/search/schedules?parametrit

Tuloksena palautetaan hakuehtoihin täsmäävien kirjastojen aikataulut. Tulosjoukko on ryhmitelty kirjastojen mukaan ja sisältää myös kirjastojen ydintiedot.

Sallitut parametrit

Kun date- tai week-parametria käytetään operaattoreiden < ja > kanssa, täytyy määrittää sekä alku- että loppuarvo!

Palveluiden massahaku

Kutsun osoitteen muoto on seuraava: http://api.kirjastot.fi/v2/search/services?parametrit

Sallitut parametrit

Tuloksena palautetaan lista palveluiden tietueista. Jaetut palvelut ovat mallipohjia, joita voidaan käyttää pohjina liitettäessä palveluita kirjastoihin. Näin voidaan saavuttaa esimerkiksi palveluiden yhtenäinen nimeäminen eri kirjastojen välillä.

<collection count="1">
    <service>
        <id>1n6Ln1SdTaGJ6v1T-yFfkQ</id>
        <type>tila</type>
        <modified>2013-05-30T15:03:39</modified>
        <price/>
        <for_loan/>
        <name multilang="true">
            <value lang="fi">Siikapalvelu</value>
            <value lang="sv"></value>
            <value lang="en"></value>
            <value lang="se"></value>
        </name>
        <tags></tags>
        <description>
            <long multilang="true">
                <value lang="fi"></value>
                <value lang="sv"></value>
                <value lang="en"></value>
                <value lang="se"></value>
            </long>
            <short multilang="true">
                <value lang="fi"></value>
                <value lang="sv"></value>
                <value lang="en"></value>
                <value lang="se"></value>
            </short>
        </description>
    </service>
</collection>

Dokumenttien rakenne

Rajapinnan palauttamissa dokumenteissa kenttien järjestys on sekalainen, eli ei voida olettaa, että kenttien järjestys oli kahta tietuetta vertaillessa sama. Tämä pätee myös silloin, kun rajapinta palauttaa monta tietuetta listana.

Yleisestä käytännöstä poiketen kirjastojen id-tunnisteet eivät ole numeerisia. Sen sijaan id:t ovat vaihtelevan pituisia merkkijonoja, joissa isoilla ja pienillä kirjaimilla on merkitystä. Id-tunnisteessa sallitut merkit ovat isot ja pienet kirjaimet (a-z), numerot (0-9) sekä tavuviiva (-).

Monikielisyyden tuki

Koska osa tietueiden kentistä on monikielisiä, voi asiakasohjelma pyytää vain tietyn kieliversion. Mikäli asiakassovellus ei määritä mitään kieltä, yksi tietue sisältää kaikkien eri kielten datan eli kieliversiot eivät ole tuloksessa omina tietueinaan.

Kirjastot voivat itse valita, mitä kieliä ne tukevat, joten eri kieliversioiden kattavuus on varsin hajanaista. Mikäli tuloksen kieliversio on määritetty mutta kyseisellä kielellä jonkin monikielisen kentän arvo on tyhjä, järjestelmä täyttää kentän automaattisesti sen suomenkielisellä vastineella.

Palautettavan kieliversion voi määrittää get-parametrilla lang. Xml-muotoisessa vastauksessa monikieliset kentät on merkitty attribuutilla multilang (multilang="true"). Kun kieliversiota ei ole määritetty, monikieliset kentät sisältävät listan value-elementtejä, joiden attribuutti lang kertoo arvon kielen.

Mikäli kieliversio on määritetty, tällöin monikielinen kenttä sisältää vain kyseisen kielen (tai ns. fallback-kielen eli suomen) datan ja multilang-kentällä on myös lang-attribuutti, joka ilmaisee kyseisen arvon todellisen kielen.

Json(p)-dokumenteissa attribuutteja ei voi käyttää, joten asiakassovelluksen täytyy itse tietää monikieliset kentät ja osata käsitellä niitä asianmukaisesti.

Kielikoodit

Kuvat

Hakemistoon voi lisätä kuvia kirjastoille. Kuvat ovat valmiiksi saatavilla eri kokoisina. Jokaisen kuvan tietueessa on osoitteet saatavilla oleviin eri kokoisiin versioihin. Kuvat on pakattu jpeg-muotoon. Kuvia ei ole ns. cropattu mihinkään tiettyyn kuvasuhteeseen vaan alkuperäiset mittasuhteet on säilytetty.

Tietotyyppien muotoilu

Erikoistietotyypit kuten päivämäärät, puhelinnumerot tai www-osoitteet ovat aina normalisoidussa muodossa.

• Päivämäärät standardissa muodossa: YYYY-MM-DD (esim. 2013-07-31).
• Kellonajat muodossa hh:ii (esim. 09:11).
• Datetime-arvot: ISO-8601-standardin mukainen esitystapa (esim. 2013-07-31T09:11).
• Puhelinnumerot kansainvälisessä muodossa: +358551234567.
• Www-osoitteet täydellisessä muodossaan sisältäen protokollan tunnisteen.
• Valuuttoja ilmaisevat arvot ovat euromääräisiä mutteivät sisällä rahayksikköä.
• Liukuluvuissa desimaalierotin on piste.

Esimerkkejä kieliversioitujen kenttien rakenteesta

Kieliversiota ei määritetty:

<library>
    <id>LTYu6-FGmQ1</id>
    <name multilang="true">
        <value lang="fi">Testikirjasto</value>
        <value lang="en">Test library</value>
    </name>
    <name_short multilang="true">
        <value lang="fi">Testi</value>
        <value lang="en"></value>
    </name_short>
</library>

{
    "id": "LTYu6-FGmQ1",
    "name": {
        "fi": "Testikirjasto",
        "en": "Test library"
    },
    "name_short": {
        "fi": "Testi",
        "en": ""
    }
}

Kieliversioksi määritetty englanti:

<library>
    <id>LTYu6-FGmQ1</id>
    <name multilang="true" lang="en">Test library</name>
    <name_short multilang="true" lang="fi">Testi</name>
</library>

{
    "id": "LTYu6-FGmQ1",
    "name": "Test library",
    "name_short": "Testi"
}