Beskrivning

Här beskrivs KBR API version 1 och dess funktioner.

Mål och funktioner

Målet med KBR API är:

• "Både Människor och Maskiner"
  Erbjuda ett tydligt API som är lätt att använda för klienten “både människor och maskiner”. Exempel: “hämta namn och byggnadsid på de första 20 kyrkorna sorterat i fallande ordning enligt namnet”
  http://[apiurl]/api/byggnader?fields=namn,id&kyrka=true&limit=20&orderby=namn-

• REST-inspirerat HTTP-gränssnitt med tydliga resurser
  Resurser är byggnader och begravningsplatser. Exempel på GET-anrop mot KBR API:
  /byggnader: de första 10 byggnaderna
  /byggnad/32555: unik byggnad på byggnadsid enligt KBR (Linköpings domkyrka i det här fallet).

• "Grunda" resurser
  Man ska inte behöva kliva ner många nivåer för att hitta det man söker, och inte heller vara tvungen att ladda oförutsägbart stora nästlade strukturer.

• Pageing
  Antal rader i ett svar är default 10 och normalt begränsat till 100 för att göra serverns arbete mer förutsägbart stort för varje anrop. I de fall multipla parametrar kan skickas in som en del av URL en i en GET request är antalet också där begränsat till 100.
  Pageingen styrs av Limit (hur många rader man max vill ha tillbaks i svaret) och Offset (var i svarsresultatet ska vi börja hämta data). Godkända värden på limit är 3-100. Genom att kombinera limit och offset kan en klient enkelt implementera server-driven paging. Exempel:
  /byggnader?limit=20&offset=100

• Valbara fields i resultatet
  Möjlighet att bestämma via Fields parameter vilka fält i svaret som ska returneras (partiella svar). Exempel: hämta namn och byggnadsid för byggnader:
  /byggnader?fields=namn,id

• Filter
  Att erbjuda Filter på resurserna för att avgränsa dem på så många olika sätt att de flesta klienters behov kan lösas “server-side”. En viss mängd filtrering på klientsidan kan ändå bli aktuell för att tillgodose mer komplexa krav. Vilka filter som stöds bestäms för varje enskild resurs (byggnader, begravningsplatser). Exempel: hämta byggnader av typen Kyrka:
  /enheter?kyrka=true

• Sortering
  OrderBy kan göras för varje resurs. Varje resurs har regler för vilka fält som OrderBy kan utföras på. Både stigande och fallande (lägg till ett “-” efter fältnamnet) stöds. Exempel:
  /byggnader?OrderBy=id: stigande ordning på byggnadsid
  /byggnader?orderby=namn-,id: fallande ordning på namn och i andra hand stigande på id.

• JSON eller XML
  JSON är standard och det som rekommenderas för klienter (maximalt kompakt, tar bara med värden som inte är null). En klient bör sätta Accept-header till “application/json” för att försäkra sig om att JSON-format returneras oavsett vad det är för typ av klient som anropar.
  XML (ofta 5 gånger så stort som JSON-svaret eller mer). Rekommenderas främst för testning då det är enklare för människor att förstå än JSON.

• Standariserade svarskoder
  KBR API använder standardkoderna från HTTP-protokollet. Exempel:
  200 OK
404 NotFound

Autentisering mot KBR API

För att anropa KBR API måste en giltig api-nyckel från Svenska Kyrkans tjänsteramverk anges. En api-nyckel är en Guid och anges på formatet xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Api-nyckeln kan bifogas på två sätt:

• Som query-parameter i URL’en:
  /byggnader?apikey=<guid>

• Som HTTP-header:
  SvkAuthSvc-ApiKey: <guid>

Installationer av KBR API

Två fristående installationer finns en för test och en för produktion.

• Test: http://api-t.svenskakyrkan.se/kbr
  Exempel:
  http://api-t.svenskakyrkan.se/kbr/api/byggnader

• Produktion: https://api.svenskakyrkan.se/kbr
  Exempel:
  https://api.svenskakyrkan.se/kbr/api/byggnader