Innholdsfortegnelse
Bibliofils WebAPI (programmeringsgrensesnitt) er todelt. Hoveddelen inneholder hovedsaklig alle funksjoner som kan brukes for å hente ut informasjon fra databasen. Dette inkluderer blant annet søking og bestandinformasjon. Den andre delen gir tilgang til funksjoner som gjør endringer i databasen. Endringer i databasen stiller større krav til autentisering.
WebAPI-et har en forholdsvis liten kostnad som skal dekke installasjon og (videre)utvikling av grensesnittene. Man kan velge å bare kjøpe hoveddelen hvis det er kun den man ønsker å bruke. Send gjerne en forespørsel til bestill@bibsyst.no for et uforpliktende tilbud.
WebAPI-et er ment å brukes av utviklere, men vi har også funksjoner som enklere kan integreres i nettsidene til biblioteket. Vi har portalvennlige versjoner av Websøket og MappaMi samt mulighet for integrasjon av en innloggingsboks for lånere i nettsidene til biblioteket.
WebAPI-et består av velkjent webteknologi. Enkelte funksjoner baserer seg på internasjonale standarder og bruker primært XML for utveksling av data, men vi har også Bibliofil-spesifikke funksjoner som bruker rene REST-grensesnitt med svar i JSON. Disse er spesielt egnet for bruk i Javascript direkte i nettsidene.
Vi forventer at biblioteket har en databehandleravtale for de delene som krever det med eventuelle eksterne aktører slik at disse har fått tilgang til å hente ut og behandle lånerdata. Bibliotek-Systemer As kan ikke ta ansvar for eventuell misbruk som skjer igjennom tilgangen som er gitt til tredjepartsaktører som er godkjent av biblioteket.
WebAPI-et er ikke skrevet i stein. Vi vil videreutvikle det i henhold til nye ønsker og krav som kommer fra kunder og deres samarbeidspartnere. Noe vil vi kunne gjøre på veldig kort tid (og som en del av standardløsningen), mens større endringer vil kreve mer utviklingstid. Kom gjerne med ønsker for vurdering.
Eksemplene i dokumentasjonen er ment å vise hvordan URL-ene bygges opp og hva man kan forvente å få i svar. For REST-servicene som krever innlogging vil de ikke kunne testes uten gyldig innlogging. For å teste må man gå mot Bibliofil-tjeneren til biblioteket man integrerer mot, hvilket betyr at man bytter ut "faretbib" med maskinnavnet til bibliotekets tjener.
Kontaktinformasjon. For et uforpliktende tilbud: bestill@bibsyst.no. For teknisk informasjon/spørsmål/feilmelding/ønsker: webapi@bibsyst.no
REST-servicene har to sikkerhetsnivåer. Begge krever bruk av HTTPS. Uthenting av ikke-konfidensiell informasjon krever autentisering vha Basic Authentication, mens lånerinformasjon og endringer i databasen krever at man har autentisert seg vha Oauth 2.0 (http://oauth.net/).
For Basic Authentication vil vi opprette en global bruker for hver implementatør (per bibliotek) som brukes når man kaller de ikke-konfidensielle REST-servicene. NB! Disse kan ikke kalles direkte ifra nettleseren da dette vil eksponere innloggingsinformasjonen som skal behandles konfidensielt av implementatør.
Oauth 2.0 autentiseringen fungerer slik at låneren blir videresendt fra ekstern side/applikasjon til Bibliofils innlogging (med informasjon om retur URL) hvor låneren logger inn med sitt lånernummer og pin/passord. Når innloggingen er gjort blir låneren videresendt tilbake til nettsida/applikasjonen med en innloggingstoken i URLen. Dette tokenet brukes så ved kall til REST-servicene. Tokenet kan sendes med i cookie eller i en POST. Vi tillater ikke at tokenet sendes med i URLen (v/GET) annet enn for testing da dette vil eksponere tokenet bl.a. i loggfilene til webtjeneren.
Innloggingssida til Bibliofil vil ta seg av å gi låneren nytt passord/pin hvis glemt og vil også støtte 2-faktor autentisering på sikt. Tredjepartsaktører vil ikke få tilgang til lånerens passord/pin ved bruk av denne løsningen.
Det er viktig at REST-servicene tar høyde for at feilsituasjoner kan oppstå hvis f.eks. tokenet har blitt gjort ugyldig. REST-servicene vil i såfall returnere status=false.
Vi vil legge inn en id og passord for integratør som brukes for å identifisere hvem som gjør kallene til REST-servicene. I tillegg vil vi registrere en URL for å begrense hvilke URLer låneren kan videresendes til fra OAuth-innloggingen.
Eksempel 1.1. OAuth
https://faretbib.bib.no/cgi-bin/oauthlogin kalles med følgende argumenter:
response_type=token client_id=<clientid> redirect_uri=<URI>
client_id for DesignFirmaX for FaretBib er:
5c57d72d57565a545925559e55ff6d68fff412f78a8991aceb51eb5ccca0feacba71cba5a3
redirect_uri skal være en URI-formatert URI tilbake til app. NB! Denne må være registrert i OAuth-oppsettet på Bibliofil-tjeneren. Den trenger ikke være komplett, men nok til at den ikke kan misbrukes. Under testingen er den satt til "https://*".
Når låneren har logget inn vil redirect_uri bli kalt med #token som må brukes for å aksessere webservicene første gang.
URLen som Appen sender låneren vil vil se slik ut:
https://faretbib.bib.no/cgi-bin/oauthlogin?response_type=token&client_id=5c57d72d57565a545925559e55ff6d68fff412f78a8991aceb51eb5ccca0feacba71cba5a3&redirect_uri=https://designfirmax.no/MyExternalApp
Etter innlogging vil låneren redirigeres til (etter vellykka innlogging):
https://designfirmax.no/MyExternalApp#02d38fb41a88d90a159e74343243243947346234732ae0d812d922eccf0b10006fa05048562
Her har man 3 valg:
Send med tokenet i HTTP-headeren:
Authorization: Bearer 02d38fb41a88d90a159e74343243243947346234732ae0d812d922eccf0b10006fa05048562
Sett en cookie med tokenet:
oa_lnr_token=02d38fb41a88d90a159e74343243243947346234732ae0d812d922eccf0b10006fa05048562
Send med i URL. NB! Dette skal kun brukes til testing da tokenet blir lagret bl.a. i Apache-loggen.
https://.....?oa_lnr_token=02d38fb41a88d90a159e74343243243947346234732ae0d812d922eccf0b10006fa05048562
Når dette kallet er gjort første gang etter innlogging vil vi opprette cookiene:
oa_lnr_expires oa_lnr_token oa_lnr_user
Det er dermed ikke nødvendig å sende med/sette token etter første kall.
Tokenet er i utgangspunktet gyldig i 6 timer og refreshes automatisk hver gang man gjør et kall som krever OAuth-autentisering. Timeout kan justeres etter behov.
Webservicene vil returnere status=false, message="Unauthorized login" hvis token er ugyldig.
Utlogging kan gjøres med redirect_uri og logout=1:
https://faretbib.bib.no/cgi-bin/oauthlogin?response_type=token&client_id=<client_id>&redirect_uri=<redirectURL>&logout=1.