In English (englanniksi): Finna Authentication API (In English)

Historia

20.3.2017 Ensimmäinen versio

Yleistä

Finnassa on rajapinta, jolla voidaan tarkistaa, ovatko asiakkaan antamat kirjautumistiedot oikein. Rajapinta palauttaa vain tiedon onnistumisesta, ei asiakkaan tietoja.

Käyttöehdot

Rajapinta ei ole avoimesti käytettävissä, vaan sen käytöstä on sovittava erikseen ottamalla yhteyttä Finnan palvelupisteeseen (finna-posti [at] helsinki.fi). Rajapinnan hyödyntäminen sallitaan vain erikseen sovituista IP-osoitteista. Rajapinnan käyttäminen edellyttää, että rajapinnan hyödyntäjä jakaa Kansalliskirjastolle sellaiset yhteystiedot, joilla käyttöön liittyviä tärkeitä viestejä saadaan nopeasti välitettyä. Rajapinnan hyödyntäjän pitää myös päivittää muuttuvia yhteystietojaan.

libraryCardLogin -rajapintakutsujen pitää lähteä liikkeelle aina käyttäjän toimesta. Kirjautumiskohde, käyttäjätunnus ja salasana voivat olla vain ja ainoastaan käyttäjän valitsemia.  

Jos vääränlaista tai palvelua haittaavaa käyttöä havaitaan, Kansalliskirjastolla on oikeus sulkea rajapinnan hyödyntäjän pääsy rajapintaan. Asiasta tiedotetaan rajapinnan hyödyntäjälle.


Merkistönä on kaikissa tapauksissa UTF-8 (composed).

Toiminnot

getLoginTargets

https://api.finna.fi/api/v1/auth/getLoginTargets?<parametrit>

Palauttaa listan targeteista (kirjastot), joihin kirjautumispyynnön voi kohdistaa. Kertoo vastauksessa myös, mikäli kirjautuminen edellyttää myös toissijaisen tiedon käyttämistä (tyypillisesti sukunimi kirjastokortin numeron ja PIN-koodin lisäksi).

ParametriTyyppiSeliteSallitut arvot
prettyPrintLukuTulostetaanko JSON rivinvaihtojen kera0 (oletus), 1
lngMerkkijonoKieliversio
  • fi (suomi, oletus)
  • sv (ruotsi)
  • en-gb (englanti)

Esimerkkikysely:

https://api.finna.fi/api/v1/auth/getLoginTargets?prettyPrint=1

Esimerkkivastaus:

{
    "targets": [
        {
            "id": "muumilaakso",
            "name": "Muumilaakson kirjasto",
        },
        {
            "id": "testi",
            "name": "Testikirjasto",
            "secondary_login_field_label": "Sukunimi"
        }
    ]
}

 

libraryCardLogin

Palauttaa tiedon kirjautumisen onnistumisesta ja mahdollisista virheistä. Parametrit tulee lähettää POST-pyynnöllä (application/x-www-form-urlencoded; charset=utf-8).

ParametriTyyppiSeliteSallitut arvot
prettyPrintLukuTulostetaanko JSON rivinvaihtojen kera0 (oletus), 1
lngMerkkijonoKieliversio
  • fi (suomi, oletus)
  • sv (ruotsi)
  • en-gb (englanti)

targetMerkkijonoKirjautumiskohde eli kirjastogetLoginTargets-pyynnön palauttamat id:t
usernameMerkkijonoKäyttäjätunnus (kirjastokortin numero) 
passwordMerkkijonoSalasana (PIN-koodi) 
secondaryMerkkijonoToinen tunnistekenttä, mikäli getLoginTargets palautti secondary_login_field_label:n 

Esimerkkikysely (tässä GET-muodossa, käytä POST-pyyntöä):

https://api.finna.fi/api/v1/auth/libraryCardLogin?target=muumilaakso&username=100010&password=12345&secondary=Muumipappa

Esimerkkivastaus onnistuneesta kirjautumisesta:

{"result":"success","status":"OK"}

Esimerkkivastaus epäonnistuneesta kirjautumisesta (tunnus tai salasana väärä):

{"result":"failure","status":"OK"}

Esimerkkivastaus, jos esim. yhteydessä kirjastojärjestelmään on ongelmia:

{"status":"ERROR","statusMessage":"Backend unavailable"}
  • No labels