KBR API har två olika resurser:
Byggnader
Två typer av byggnader finns i KBR: Kyrkor och Övriga byggnader. Det som skiljer typerna åt är antalet fält som returneras i svaret från KBR API. Kyrkor innehåller alla fält som Övriga byggnader gör plus ett antal extrafält.
Byggnader kan byta typ mellan Kyrkor och Övriga byggnader (via ändringar i KBR). Detta är anledningen till att båda typerna efterfrågas via samma sökväg (/byggnader).
Begravningsplatser
Saknar vidare indelning, samma fältuppsättning returneras för alla objekt.
Här följer förklaringar till begrepp som används av anrop till de olika resurserna.
Varje resurs har defaultfält som alltid returneras om användaren inte bestämmer vilken information som ska returneras (se Fields nedan). Defaultfälten är:
Namn. Namnet på resursen, en sträng med maxlängd på 50 tecken.
ID. KBR-id’t på resursen ett heltal med 5 siffror.
Fields styr partiella svar, dvs bestämer hur stor del av informationsmängden som hör till resursen som ska tas med. Exempel:
fields=*: ta med alla fält på objektet. Default (om inte fields anges alls) tas ett minimum av grundläggande fält med, men klienten förväntas använda fields för att hämta precis det som är intressant.
fields=namn,id,pastorat,stift: ta med namn, byggnadsid, pastorat och stift i resultatet.
Filter används för att söka ut en delmängd av en resurs. Filter kan vara av tre olika typer: Exakt match, Multipla värden och Wildcard. Vilka fält som kan användas som filter och vilken typ av filtrering som fältet stödjer framgår av dokumentationen av resurserna nedan. All matching är case insensitive, dvs. bryr sig inte om stora eller små bokstäver.
Exempel på de olika typerna:
Exakt match:
namn=mariakapellet
namn=linköpings%20domkyrka: Mellanslag ska URL enkodas
Multipla värden: Matchar en eller flera värden separerade av kommatecken. Kan ej kombineras med wildcardmatchning.
id=34368,32555,32494
Wildcard: Används för att matcha delar av eller början av strängar.
^ (taktecknet): Matchar början av en sträng. Exempel: ”^bot” hittar ”boteå församling” och ”botkyrka församling” mfl.
~ (tildetecknet): Matchar del av en sträng. Exempel: ”~bot” hittar ”boteå församling” och ”sollefteå-boteå pastorat” mfl.
Gemensamt för dessa filter är att man kan ange både exakta datum och intervaller. Datum ska alltid anges som ett komplett datum på formatet “ÅÅÅÅMMDD” t.ex. “20150317”. Följande varianter finns:
“20150317”: ett exakt datum.
“20150317-”: ett öppet intervall där datum måste vara större än eller lika med “20150317”.
“-20150317”: ett öppet intervall där datum kan vara ett datum till och med “20140215”.
“20150301-20150317”: ett stängt intervall som datum måste ligga inom.
“-”: vilket värde som helst (spelar ingen roll om datum är satt eller inte).
Som en del av dokumentationen och för att få hjälp att testa KBR API och se vilket resultat ett visst anrop kan få med en viss uppsättning fields finns statiska testdata för de olika resurserna. Exempel:
api/byggnader?fields=*&testdata=true. Returnerar tre byggnader ifyllda med testdata i alla fält.Tips: Det går att få fler träffar med testdata genom att ange limit för max antal träffar. Exempel för att få ut 50 träffar med alla fält ifyllda med testdata: api/byggnader?fields=*&limit=50&testdata=true. Det finns också stöd för offset, så att man kan simulera paging. Det fungerar så att man får ut “limit * 3 + 3“ objekt. Exempel:
api/byggnader?kyrka=true&testdata=true&limit=10 → 10 enheter
api/byggnader?kyrka=true&testdata=true&limit=10&offset=10 → 10 kyrkor
api/byggnader?kyrka=true&testdata=true&limit=10&offset=20 → 10 kyrkor
api/byggnader?kyrka=true&testdata=true&limit=10&offset=30 → 3 kyrkor