Dette er den viktigste delen av WebAPI-et og den som de fleste vil benytte seg av. Flere av funksjonene er allerede tilgjengelig på mange bibliotek, så sjekk gjerne om dere allerede har det dere trenger.
OAI-PMH (https://www.openarchives.org/OAI/openarchivesprotocol.html) er en standard internasjonal innhøstingsprotokoll som primært brukes av Nasjonalbiblioteket for innhøsting av katalogpostene til bibliotekene. Dette er protokollen som ligger i bunnen av Biblioteksøk og målet til Nasjonalbiblioteket er at alle folkebibliotek skal ha dette etterhvert. Bibliofils OAI-PMH-tjener støtter deleted records og OAI-PMH sets.
Følgende metadataPrefix er tilgjengelig:
Tabell 1.1. metadataPrefix
| Prefix | Forklaring |
|---|---|
| dc | Dublin Core |
| marcxchange | Normarc i MarcXchange |
| bibliofilmarc | Full Bibliofilpost med $3 i MarcXchange |
| bibliofilmarcnoholdings | Full Bibliofilpost med $3 i MarcXchange, men uten beholdningsdata |
| noholdings | Samme som MarcXchange, men uten beholdningsdata |
Oversikt over tilgjengelige OAI-PMH-tjenere finnes her: https://bibsyst.no/oaiservere.html. Her er også informasjon om OAI-PMH-repositoryet er allment tilgjengelig eller om det er begrenset til spesifikke IP-adresser.
Hvis biblioteket har OAI-PMH vil det være tilgjengelig på https://maskinnavn.bib.no/cgi-bin/oai. Se ?verb=Identify for mer informasjon om repositoryet. "maskinnavn" er hostnavnet på Bibliofil-tjeneren.
Da OAI-PMH er en ren innhøstingsprotokoll er den lite brukt utenfor Biblioteksøk. Vi henviser derfor til Open Archives Initiative for mer informasjon om denne protokollen.
Z39.50 er en binær søkeprotokoll som brukes mye på det norske bibliotekmarkedet, men vi anbefaler at man ikke lager nye løsninger basert på den så fremt man ikke må. Dette fordi videreutviklingen av Z39.50 på det norske markedet har stoppet opp og biblioteksystemleverandørene driver kun med vedlikehold og feilretting for denne protokollen.
Søking har vi gjort tilgjengelig igjennom en XML-basert internasjonal søkeprotokoll. Bibliofils SRU-tjener er i henhold til SRU-standarden v1.2 (http://www.loc.gov/standards/sru/) samt norsk profil (som er definert på http://norzig.no/sru/profile/1.2/).
SRU-tjeneren støtter følgende recordSchema:
Tabell 1.2. SRU recordSchema
| recordSchema | Forklaring |
|---|---|
| dc | Dublin Core |
| zeerex | Explain Schema |
| normarc | Normarc i MarcXchange |
| bibliofilmarc | Full Bibliofilpost med $3 i MarcXchange |
| bibliofilmarcnoholdings | Full Bibliofilpost med $3 i MarcXchange, men uten beholdningsdata |
| noholdings | Samme som MarcXchange, men uten beholdningsdata |
| bsdc | Dublin Core, med ekstra Bibliofil-spesifikke tagger |
Vi anbefaler at man bruker dc eller bsdc hvis man ikke er ute etter komplette katalogposter eller beholdningsdata i 850-taggene.
Oversikt over tilgjengelige SRU-tjenere ligger her: https://bibsyst.no/z3950tabell.html. Alle som har kjøpt Z39.50 har også SRU da vi ser på det som en videreutvikling/erstatning for Z39.50.
Tilgjengelige søkeindekser kan fås ved å kalle https://maskinnavn.bib.no/cgi-bin/sru. De som ligger i context settet bibliofil er Bibliofil-spesifikke, mens de andre er enten fra SRU-standarden eller Norzig-profilen.
Bibliofils SRU-tjener har en utvidelse for å få støtte for fasetter. Ved å sende med extraRequestData=bibliofil:fasetter:1 vil fasetter legges med i svaret i extraResponseData. Tallet 1 indikerer fasettnivået. 1 betyr at man skal maks returnere 1 treff per type fasett. Man står fritt til å øke den etter behov, men desto høyere, desto større (og tregere) svar må forventes. Det er viktig å være klar over at det ligger en kostnad i tidsbruk ved å be om fasetter, da dette betyr at SRU-tjeneren må løpe igjennom alle treffene og hente ut fasettinformasjonen. Hvis man har store trefflister er man ikke garantert at tjeneren klarer å svare innenfor fornuftig tid.
Det er mulig å be om andre typer sorteringer enn standard, men de krever en gjennomløping av treffene og vil derfor medføre til at søkene går tregere. Vi støtter sortering på creator, title, date, spatial. Eks: sortKeys=date,,false,false,highValue (sorterer på utgiverår, ingen schema, !ascending, !caseSensitive, missingValue=highValue). Dette er defaultverdiene, så man får samme resultat med sortKeys=date.
SRU-tjeneren støtter også scan i tillegg til searchRetrieve. F.eks. operation=scan&scanClause=dc.title vil returnere indekserte tittel-termer fra databasen (fra emneregisteret).
SRU-tjeneren støtter kun basisprofilen for CQL med noen få unntak. Trunkering (høyre) kan brukes, men det kreves minst 2 tegn for at det skal være gyldig. Forespørselen vil bli automatisk avbrutt hvis søket tar mer enn 60 sekunder.
Eksempel 1.2. SRU
GET Request:
https://kongbib.bib.no/cgi-bin/sru?operation=searchRetrieve&recordSchema=dc&query=nesbø
Respons:
<?xml version="1.0" encoding="utf-8"?>
<SRU:searchRetrieveResponse xmlns:SRU="http://www.loc.gov/zing/sru/"
xmlns:dc="info:sru/schema/1/dc-v1.1"
xmlns:normarc="info:lc/xmlns/marcxchange-v1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:DIAG="http://www.loc.gov/zing/sru/diagnostics/">
<SRU:version>1.2</SRU:version>
<SRU:numberOfRecords>80</SRU:numberOfRecords>
<SRU:resultSetId>833</SRU:resultSetId>
<SRU:nextRecordPosition>11</SRU:nextRecordPosition>
<SRU:records>
... treffliste ...
</SRU:records>
</SRU:searchRetrieveResponse>
Svaret inneholder antall treff, en resultSetId som kan brukes for å få de neste treffene og hvilken posisjon det neste treffet (som ikke er inkludert i svaret) vil ha. Selve treffene er ikke tatt med i dette eksempelet.
Treffene vil se slik ut ved bruk av dc:
<SRU:record>
<SRU:recordSchema>
info:srw/schema/1/dc-v1.1</SRU:recordSchema>
<SRU:recordPacking>xml</SRU:recordPacking>
<SRU:recordData>
<dc>
<dc:title>Arme riddere</dc:title>
<dc:description type="abstract">Vettskremt og blodig
våkner Oscar Svendsen med en hagle i hendene i det som en
gang var en anstendig strippebule ved Svinesund. Rundt
ham ligger åtte lik, og foran ham står politietterforsker
Solør og peker på ham med en pistol. For Solør fremstår
det klart at han er den skyldige selv om Oscar hardnakket
bedyrer sin uskyld. Nølende begynner Oscar å fortelle den
utrolige historien om fire karer som sammen fikk tolv
rette i tipping og nesten to millioner kroner i fanget.
Pengene skulle vise seg å være vanskelig å dele på
fire.</dc:description>
<dc:publisher>Nordisk film</dc:publisher>
<dc:date>2012</dc:date>
<dc:format id="material">video</dc:format>
<dc:identifier id="localid">94529</dc:identifier>
<dc:identifier id="bibliofilid">8235056</dc:identifier>
<dc:language>nob</dc:language>
</dc>
</SRU:recordData>
<SRU:recordPosition>1</SRU:recordPosition>
</SRU:record>
maximumRecords (antall treff man får returnert i hvert svar) er standard 10, men kan økes opp til maksimalt 500 ved å sende den med i URL.
CCL-søk i SRU:
https://kongbib.bib.no/cgi-bin/sru?operation=searchRetrieve&query=bibliofil.ccl=%22plass=krim%22&recordSchema=dc&extraRequestData=bibliofil:fasetter:1
Eksempel 1.3. Nyeste titler ("kikkhull")
https://auhobib.bib.no/cgi-bin/sru-test?operation=searchRetrieve&recordSchema=bsdc&query=norzig.materialType=l&maximumRecords=30&extraRequestData=bibliofil:stat:nyeste:30:30:1:&responseType=application/json
Formatet på extraRequestData er bibliofil:stat:nyeste:<antall titler>:<max ventetid>:<krevforsidebilde>:<eieravdelingskode>. Max ventetid er om den skal avbryte etter en viss tid. Denne funksjonen bruker statistikken i bunnen og er ikke rask. Det anbefales at bruk av denne (eller RSS) blir gjort i bakgrunnen og pregenerert til ei side slik at vanlige brukere ikke trenger å vente.
Krevforsidebilde kan være 1 eller 0. 1 begrenser treffene til de som har forsidebilder.
Pass på at maximumRecords er lik eller høyere enn antall titler hvis man ikke vil at den skal begrense antall returnerte treff. responseType kan settes til text/javascript hvis man vil ha JSONP.
Hvis du vil bruke CCL-søk istedet for SRU CQL, bruk søkeindeksen bibliofil.ccl.
Alle Bibliofil-bibliotek har tilgjengelig RSS-strømmer for ting som nye titler, mest utlånte, etc. En enkel RSS kan lages ved å sende med ccl=-argumentet til /cgi-bin/rss. Det er også mulig å sende med bibxml=1 for å få med enkelte katalogspesifikke tagger samt noe KatalogKrydder hvis det er tilgjengelig.
RSS er beskrevet i Statistikkhåndboken: https://bibsyst.no/web/tkstat/rss.html.
Tilgang til KatalogKrydder er begrenset med IP-adresse og kan i utgangspunktet ikke benyttes direkte fra nettleseren. Tilgang kan kjøpes separat fra WebAPI-et hvis det er ønskelig.
API-et mot KatalogKrydder er XML-basert. Kall mot krydderxml består av en GET som inneholder Bibliofil-ID (en Bibliofil-spesifikk identifikator som brukes for å unikt identifisere verk) for å finne krydder for et spesifikt verk. Det finnes krydder for de fleste dokumenttyper, ikke bare for bøker. Krydder legges inn av bibliotekene selv i en dugnadsinnsats. Typer krydder som finnes er forsidebilder, beskrivelser, innholdsfortegnelser, anmeldelser (av lånere), stjernekast, etc.
Svarformat er enten xml (default) eller json: format=json
Eksempel 1.4. KatalogKrydder
Request:
https://krydder.bib.no/cgi-bin/krydderxml?bibid=64286
Respons:
<?xml version='1.0' encoding='utf-8'?>
<krydder xmlns="http://krydder.bib.no/cgi-bin/krydderxml">
<item>
<bibliofilid>64286</bibliofilid>
<kryddertyper>bilde beskrivelse</kryddertyper>
<krydder_bilde>
<type>forside</type>
<bildedata>
<størrelse>256x</størrelse>
<url>https://krydder.bib.no/0395/64286.bilde.1327560326.n.jpg</url>
</bildedata>
<bildedata>
<størrelse>ekstrastor</størrelse>
<url>https://krydder.bib.no/0395/64286.bilde.1327560326.x.jpg</url>
</bildedata>
<bildedata>
<størrelse>medium</størrelse>
<url>https://krydder.bib.no/0395/64286.bilde.1327560326.m.jpg</url>
</bildedata>
<bildedata>
<størrelse>karusell</størrelse>
<url>https://krydder.bib.no/0395/64286.bilde.1327560326.k.jpg</url>
</bildedata>
<bildedata>
<størrelse>liten</størrelse>
<url>https://krydder.bib.no/0395/64286.bilde.1327560326.l.jpg</url>
</bildedata>
<bildedata>
<størrelse>stor</størrelse>
<url>https://krydder.bib.no/0395/64286.bilde.1327560326.s.jpg</url>
</bildedata>
</krydder_bilde>
<krydder_beskrivelse>
<type>forlagstekst</type>
<url>http://krydder.bibsyst.no/0395/64286.beskrivelse.1327560327.xml</url>
<tekst>Forlaget skriver om denne boka:<br> "Paul Auster
har skrevet en glassklar og vakker bok, en bok med nesten
nifs gjennomsiktighet og åpenhet" - slik presenterer Jan
Kjærstad New York-trilogien i Bokspeilet, Bokklubben nye
bøkers medlemsblad. Det er tre bøker sm her kjem i eitt band,
<em>Glasbyen, Gjengangarar og Det stengde
rommet</em>. I den danske avisa Eksta Bladet skriv Poul
Borum om trilogien: "Det er kriminalromaner, der samtidig
leger med fiktionen og har noget væsentligt at sige. Auster
bruger virtuost alle klicheerne fra Raymond Chandler osv. og
blander dem med Borges og Poe (og Lewis Carroll og Cervantes
og meget mere), og mixer alle disse elementer til en
forbløffende og forrygende labyrintisk fortælling med vittig
leg med identiteter."<br> Den amerikanske forfatteren
Paul Auster er fødd i 1947, universitetsutdanna litterat, har
også vore sjømann og budd i Frankrike ei tid. No bur han
Brooklyn, New York. Han understrekar gjerne at han er
jøde.</tekst>
</krydder_beskrivelse>
</item>
</krydder>
Eksempel 1.5. KatalogKrydder som json
Request:
https://krydder.bib.no/cgi-bin/krydderxml?bibid=64286&format=json
Respons:
{
"status" : "OK",
"statusmelding" : "",
"64286" : {
"kryddertyper" : ["bilde","beskrivelse"],
"krydder_bilde" : [{
"epoc" : "1327560326",
"type" : "forside",
"størrelser" : ["k","l","m","n","s","x"],
"url" : "https://krydder.bib.no/0395/64286.bilde.1327560326.m.jpg"
}],
"krydder_beskrivelse" : [{
"epoc" : "1327560327",
"type" : "forlagstekst",
"url" : "http://krydder.bibsyst.no/0395/64286.beskrivelse.1327560327.xml",
"tekst" : "Forlaget skriver om denne boka:<br>\n\"Paul Auster har skrevet en glassklar og vakker bok, en bok med nesten nifs gjennomsiktighet og åpenhet\" - slik presenterer Jan Kjærstad New York-trilogien i Bokspeilet, Bokklubben nye bøkers medlemsblad. Det er tre bøker sm her kjem i eitt band, <em>Glasbyen, Gjengangarar og Det stengde rommet</em>. I den danske avisa Eksta Bladet skriv Poul Borum om trilogien: \"Det er kriminalromaner, der samtidig leger med fiktionen og har noget væsentligt at sige. Auster bruger virtuost alle klicheerne fra Raymond Chandler osv. og blander dem med Borges og Poe (og Lewis Carroll og Cervantes og meget mere), og mixer alle disse elementer til en forbløffende og forrygende labyrintisk fortælling med vittig leg med identiteter.\"<br>\nDen amerikanske forfatteren Paul Auster er fødd i 1947, universitetsutdanna litterat, har også vore sjømann og budd i Frankrike ei tid. No bur han Brooklyn, New York. Han understrekar gjerne at han er jøde.\n"
}]
}
}
For en oversikt over hva som er tilgjengelig og en enkel hjelpetekst kan man kalle KrydderXML direkte uten argumenter: https://krydder.bib.no/cgi-bin/krydderxml.
WebAPI-et har noen funksjoner tilgjengelig igjennom REST-kall som returnerer JSON-kode som enkelt kan behandles i f.eks. Javascript. Noen av disse er kun tilgjengelig over HTTPS og krever autentisering.
Full beholdningsdata med enkel tittelinformasjon og eventuelt KatalogKrydder hvis dette er tilgjengelig. Krever ikke autentisering (ingen lånerdata).
items brukes for å hente ut katalogdata og lenker til eksemplarene. copies gir eksemplarinformasjon for tittelen.
Identifikatoren er det lokale tittelnummeret i basen (i eksempelet 325234). Identifikatoren kan bestå av flere tittelnumre separert med komma.
Innholdet i svaret fra items bestemmes av maler i Bibliofils websøk og kan tilpasses der.
Eksempel 1.6. items og visningsmaler
https://tbgbib.bib.no/cgi-bin/rest_service/items/1.0/data/325234,54231?postformat=kort
Eksemplet ber om formatmalen kort. Tilgjengelige maler kan variere fra bibliotek til bibliotek. I utgangspunktet har alle følgende formater: default, kortformat, forhand, isbd, wap, tidsskrift, bilde, bilde-ekstra, bilde-deich, dikt, kort, DC, nettressurs, originalspraak, lydbib-komplett, lydbib. Noen av disse er spesike for enkeltbibliotek, og kan være endret eller slettet av andre.
Nye visningsformat kan defineres i innstillingene for websøket ( → → → → ).
Eksempel 1.7. GET Request for items
https://tbgbib.bib.no/cgi-bin/rest_service/items/1.0/data/325234
Respons:
{
"325234":{
"Tittel": ["Dying to tell"],
"Forfatter": ["Goddard, Robert , Engelsk 1954-"],
"Språk": ["engelsk"],
"Utgitt": ["London : Bantam , 2001"],
"Omfang": ["345 s."],
"Opplysninger": ["Engelsk tekst","%brefr2-TbgBib-1347369284952","LOCAL-ID","0000","Goddard, Robert","NO:02070400:1007040176061001 ::07040176061001"],
"Sjanger": ["Krim"],
"ISBN": ["0-593-04762-1","(h.)","155.00"],
"Hylleplass": ["82 G"],
"bibliofilid":2142206,
"copies":"https://tbgbib.bib.no/cgi-bin/rest_service/copies/1.0/data/325234?fields=full&exfields=full"}>,
"duration":232,"time":"20160622-1340-29 +0200"
}
Eksempel 1.8. GET Request for copies
https://tbgbib.bib.no/cgi-bin/rest_service/copies/1.0/data/325234?fields=full&exfields=full
Respons:
{
"elements":
{"325234":{
"bibliofilid":2142206,
"total":0,
"available":0,
"holds":0,
"copies":[]}
},
"length":1,"updatetime":"2016-06-22 1348-14:+0200","duration":90,"apiver":"1.0-beta1"
}
Hvis man ikke tar med fields og exfields vil man få en kort variant med kun totaltall.
Det er mulig å ta ut både items og copies i en request slik: https://larbib.bib.no/cgi-bin/rest_service/items/1.0/data/25231?fields=full&holdings=1
Mer informasjon kan få ved å ta opp REST-servicen uten argumenter: https://larbib.bib.no/cgi-bin/rest_service/copies.
For å få ut JSONP, må det sendes med en vilkårlig streng i argumentet jsoncallback. Den verdien blir da lagt inn som et funksjons-kall rundt json-koden. Dette er nødvendig dersom dataene skal bli hentet ut via javascript fra et annet domene.
Autentisering: Ingen. Anonyme data.
Henter ut liste over avdelinger på biblioteket. Default returneres henteavdelingene hvis biblioteket har satt dette opp. Bruk type=alle for å få alle avdelinger.
Eksempel 1.9. getDepartments
Request:
https://faretbib.bib.no/rest_service/webapi_getDepartments/1.0/data
Respons:
{
"status" : true,
"serverdate" : "2016-04-28T13:24:03",
"departments" : [{
"code" : "fhb",
"name" : "Faret Hovedbiblioteket"
{,}
"code" : "fhbv",
"name" : "Faret Hovedbiblioteket voksen"
}]
}
Autentisering: Krever gyldig innlogging vha Basic Authentication.
Oversettelse av strekkode/RFID til tittelnummer og eksemplarnummer.
Parameter: barcodeId // Strekkode/RFID
Return: Et objekt som inneholder unique_material_id, local_id and bibliofil_id for barcodeId.
Eksempel 1.10. translateBarcode
https://faretbib.bib.no/rest_service/webapi_translateBarcode/1.0/data?barcodeId=06040000019007
{
"status" : true,
"message" : "",
"serverdate" : "2016-04-15T11:17:50",
"material" : {
"bibliofilid" : 131371,
"localId" : 19,
"loanId" : "ix:19,7"
}
}
Autentisering: Krever gyldig innlogging vha Basic Authentication.
Henter ut bibliotekinformasjon.
Funksjon: getBranches
Parametere: Ingen
Returnerer: Array med bibliotek. Som regel er dette bare ett, men det kan teoretisk være flere.
branch object:
{
code: string, // Unik forkortelse for biblioteket, oftest er dette "main".
name: string, // Bibliotekets fulle navn
longitude: float|null,
latitude: float|null
}
Eksempel 1.11. getBranches
https://faretbib.bib.no/rest_service/webapi_getBranches/1.0/data
{
"status" : true,
"message" : "",
"serverdate" : "2016-04-15T11:12:13",
"branch" : [{
"code" : "main",
"name" : "Kongsberg bibliotek",
"latitude" : "59.664926,",
"longitude" : "9.645268"
}]
}
Autentisering: Krever gyldig innlogging vha Basic Authentication.
Henter ut informasjon om autentisert låner.
Funksjon: userinfo
Eksempel 1.12. userinfo
Eksempel: https://faretbib.bib.no/cgi-bin/rest_service/oawebapi_userinfo/1.0/data
{
"status" : true,
"message" : "",
"serverdate" : "2016-08-09T15:48:08",
"userinfo" : [{
"navn" : "Nordmann, Ola",
"adresse1" : "Kongeveien 99",
"adresse2" : "",
"postnr" : "0202",
"poststed" : "OSLO"
}]
}
Autentisering: Krever OAuth 2.0 autentisering.
Henter ut reserveringer.
Eksempel 1.13. requests
https://faretbib.bib.no/cgi-bin/rest_service/oawebapi_requests/1.0/data
Respons:
{
"status" : true,
"message" : "",
"serverdate" : "2016-08-09T15:38:13",
"requests" : [{
"idx" : "res:4188,102",
"res_dat" : "2016-08-08",
"res_hentavd" : "mbhv",
"res_hentavdeling" : "Moss hovedbibliotek",
"ordord" : "Heyerdahl, Thor",
"tittel" : "Påskeøya : en gåte blir løst",
"material" : "Bok",
"qpos" : 2
},{
"idx" : "res:42675,101",
"res_dat" : "2016-09-22",
"res_hentavd" : "mbhv",
"res_hentavdeling" : "Moss hovedbibliotek",
"ordord" : "McCourt, Frank",
"tittel" : "Engelen på det sjuende trinn : en irsk barndom",
"material" : "Bok",
"qpos" : 13
}]
}
Autentisering: Krever OAuth 2.0 autentisering.
Henter ut lånernummer basert på e-postadresse og/eller fødselsnummer. Vi anbefaler at man bruker begge (i samme kall) for å få bedre treffsikkerhet.
Det er også mulig å kalle getLnr med lnr=lånernummer for å finne alder/kjønn på en gitt låner.
Returnerer: Et array som inneholder lånernummeret. Hvis låneren har nasjonalt lånernummer vil man få dette, ellers det lokale lånernummeret. I tillegg vil man få alder (alder er "0" på de som mangler fødselsdato) og kjønn (x=ikke satt, u=ukjent, m=mann, k=kvinne).
Eksempel 1.14. getLnr
https://faretbib.bib.no/rest_service/webapi_getLnr/1.0/data?epost=roger@bibsyst.no
{
"status" : true,
"message" : "",
"serverdate" : "2016-09-15T15:50:32",
"lnr" : "N000099999"
"alder" : "43",
"kjønn" : "m"
}
Status vil være true hvis forespørselen gikk igjennom. lnr vil være "" hvis oppslaget feilet (fant ikke låneren).
NB! Hvis man bruker fødselsnummer (fnr) MÅ man sende dette med i en POST. Fødselsnummeret er sensitivt nok til at det ikke bør havne i loggen til webtjeneren.
Autentisering: Krever Basic Authentication
Brukes til å autentisere en låner med lånernummer og PIN.
Parametere:
Returnerer info om kombinasjon lnr/pin er korrekt. lnr kan også være lånerens e-postadresse. Denne vil ikke bli godkjent hvis denne e-postadressen finnes på flere enn en låner.
Eksempel 1.15. bibauth
https://host.bib.no/cgi-bin/rest_service/bibauth/1.0/data?lnr=N121212345&pin=1345
{
"success" : true,
"message" : "",
"timeout" : 60
}
success vil være true dersom kombinasjonen stemmer.
Hvis det gjøres 3 forsøk på autentisering som feiler så kan det ikke gjøres andre autentiseringer på denne låneren før det antall sekunder som står i verdien timeout er passert.
Autentisering: Krever oppsett med filtrering på IP-adresse.