Kirjastohakemiston rajapinta

Tämä dokumentti määrittelee Kirjastot.fi:n kirjastohakemiston REST-­ra­ja­pinnan, jonka kautta voi lukea kirjastojen tietoja.

Pääpalvelin on api.kirjastot.fi, sen alias on api1.kirjastot.fi ja varapalvelin on osoitteessa api2.kirjastot.fi Jos mahdollista, tulee varapalvelinta käyttää virhetilanteissa.

Kaikkiin rajapintakutsuihin liitetään rajapinnan versionumeron kokonaislukuosa ('v' sekä numero pisteen vasemmalla puolella), esim: api.kirjastot.fi/v1/

Rajapinnasta haetun datan tallentaminen dataa käyttävän järjestelmän vä­li­muis­tiin on suositeltavaa.

Mikäli mahdollista, tieto tulee jättää välimuistiin talteen erilaisia poikkeustilanteita varten, joissa datan hakeminen rajapinnasta estyy.

Rajapintaan kohdistuvien pyyntöjen määrän on pysyttävä kohtuullisena, esim. max 50 pyyntöä minuutissa.

Suositeltavinta on noudattaa HTTP:n välimuisteja koskevia otsakkeita:

Cache-Control: max-age
Expires

Kannattaa siis käyttää välimuistiin tallennettua versiota datasta niin pitkään kuin se ei ole näiden otsakkeiden mukaan vanhentunutta.

Jos em. otsakkeita ei voi käyttää, hyvä perusaika välimuistiin tallennetun tiedon vanhenemiselle on 10 minuuttia, jolloin kirjastohakemistoon tehdyt korjaukset ja muutokset tulevat kohtuullisella viiveellä julkaisujärjestelmään.

Rajapintakutsut noudattavat HTTP:n Accept-otsaketta. Jos datan haluaa JSON-muodossa, oikea otsake on Accept: application/json, ja vastaavas­ti XML-muodossa Accept: application/xml.

Jos Accept-otsakkeiden käyttö ei ole mahdollista, ks. formaatin määrittäminen kutsuparametreista (myöhemmin): esim. format=json tai format=xml.

XML-versio on suoraviivainen muunnos JSON-versiosta, toisin sanoen JSON-formaatin avaimet vastaavat XML-formaatin tagin nimeä, JSON:in arvot ovat XML-formaatin tagin tekstisisältö. XML-attribuuttien arvoja ei käytetä tietosisällön välittämiseen.

JSON-versiossa esiintyvien nimeämättömien rakenteisten olioiden elementtinimi XML-versiossa on object. Esimerkiksi hakutuloksissa yhden kirjaston tiedot on esitetty yhden <object></object>-tagiparin sisällä.

Esimerkiksi alla on osa JSON-dokumentista.

{
    "branch_type": "default",
    "consortium": "helmet",
    "contact": {
        "building_architect": "Arkitektbyr\u00e5n Pekka Salminen KY",
        "building_en": "",
        "building_fi": "Kanneltalo",
        "building_interior_designer": "Arbetsgruppen (?) Osmo Honkanen, Markku Liukkonen och Pekka Salminen",
        "building_se": "",
        "building_sv": "Gamlasg\u00e5rden",
        "building_year": "1992",
        "coordinates": "24.8762093603988,60.2388470216001,0",
        "directions_en": "",
        "directions_fi": "M-juna (Vantaankosken rata), Bussit 41,42,43,43b (40-sarja)",
        "directions_se": "",
        "directions_sv": "",
        "email": "kannelmaen_kirjasto@hel.fi",
        "homepage_en": "http://www.lib.hel.fi/en-gb/kannelmaki",
        "homepage_fi": "http://www.lib.hel.fi/fi-FI/kannelmaki/",
        "homepage_se": "",
        "homepage_sv": "http://www.lib.hel.fi/sv-fi/kannelmaki"
  }
}

Vastaavat tiedot XML-muodossa:

<branch_type>default</branch_type>
<consortium>helmet</consortium>
<contact>
    <building_architect>Arkitektbyrån Pekka Salminen KY</building_architect>
    <building_en></building_en>
    <building_fi>Kanneltalo</building_fi>
    <building_interior_designer> Arbetsgruppen (?) Osmo Honkanen,
        Markku Liukkonen och Pekka Salminen
    </building_interior_designer>
    <building_se></building_se>
    <building_sv>Gamlasgården</building_sv>
    <building_year>1992</building_year>
    <coordinates>24.8762093603988,60.2388470216001,0</coordinates>
    <directions_en></directions_en>
    <directions_fi> M-juna (Vantaankosken rata),
        Bussit 41,42,43,43b (40-sarja)
    </directions_fi>
    <directions_se></directions_se>
    <directions_sv></directions_sv>
    <email> kannelmaen_kirjasto@hel.fi</email>
    <homepage_en>http://www.lib.hel.fi/en-gb/kannelmaki</homepage_en>
    <homepage_fi>http://www.lib.hel.fi/fi-FI/kannelmaki/</homepage_fi>
    <homepage_se></homepage_se>
    <homepage_sv> http://www.lib.hel.fi/sv-fi/kannelmaki</homepage_sv>
</contact>

JSON on ensisijainen formaatti. Muunnos on suoraviivainen, eikä XML:lle ole määritelty skeemoja tai dokumenttityyppimäärityksiä.

XML:n merkistökoodaus on UTF-8.

JSON:in merkistökoodaus noudattaa IETF:n JSON-spesifikaation RFC:n 4627 http://tools.ietf.org/html/rfc4627 (kappale 2.5) tapaa merkitä ASCII-merkistön ulkopuoliset merkit.

Tietojen hakeminen rajapinnasta onnistuu HTTP GET-pyynnöillä, joissa parametrit annetaan suoraan URL:in query-parametreina.

URL-osoitteita varten ASCII-merkistön ulkopuoliset merkit muunnetaan ensin UTF-8-koodauksen mukaiseksi merkkijonoksi jonka UTF-tavut koodataan prosenttimerkin avulla: http://tools.ietf.org/html/rfc3986.