Innehållsförteckning

Revisionshistorik

1. Inledning

SDK Adressbok:s Sök-API är ett gränssnitt som erbjuder externa system läsåtkomst till information i SDK Adressbok.

Teknisk guide Adressbok API är framtaget som stöd för utvecklare vid implementation av integration mot SDK Adressbok från Meddelandetjänst och Meddelandeklient. Guiden förutsätter att målgruppen har kunskap om SDKs övergripande arkitektur och egen implementation av SDKs meddelandelager (Meddelandetjänst) och verksamhetslager (Meddelandeklient).

Denna guide kompletterar existerande API-dokumentation, se “Dokumentation”. API-dokumentationen genereras från källkod och driftsätts som en del av Adressbokens mjukvara. Detta borgar för att API-dokumentationen är aktuell i förhållande till driftsatt API. Vid ändringar med påverkan på API kommer alltså även den tekniska API-dokumentation att ändras.

SDK Adressbok informationsmodell, se /wiki/spaces/OISDK/pages/2716664009, beskriver vilken information som Sök-API:et hanterar.

1.1 Målgrupp

• Systemägare

• Systemförvaltare

• Systemarkitekt

• Utvecklingsteam

2. Översikt Adressboks-API

SDK Adressbok är ett gemensamt adressregister innehållande anslutna användarorganisationer och deras adresserbara funktioner. För generell information om SDK Adressbok, se: Vad är SDK Adressbok

Adressbokens API:er erbjuder externa system läsåtkomst till information i SDK Adressbok.

2.1 Syfte

Adressbokens API är tänkt att nyttjas av Meddelandeklienter och Meddelandetjänster.

Användningsområdena innefattar:

• Sökfunktion i grafiska gränssnitt

• Tillhandahålla kodverk som används i SDK Adressbok (kodverk används vid strukturerad sökning)

• Kontroll av information för adressering, för sk. “routing” av meddelande i en Meddelandetjänst

2.1 Informationsstruktur

Adressbokens Sök-API är en implementation av /wiki/spaces/OISDK/pages/2716664009 som baseras på standarden JSON:API, se https://jsonapi.org/ .

2.2 Adressbok Sök-API

Adressbokens Sök-API exponerar resurserna “Organizations” och “Addresses”.

2.2.1 API URL

2.2.2 Dokumentation

2.3 Adressbok Kodverksregister-API

2.3.1 API URL

2.3.2 Dokumentation

3. Rekommendation vid integration och tillämpning av Sök-API

Notera att adressbokens API:er är framtagna med direkt integration i åtanke och är anpassade för att hantera stora volymer av samtidiga anrop per sekund. Tanken är inte att klienter skall läsa av informationen och hålla en långlivad lokal cache, eftersom detta medför risk för icke-aktuell information.

Dock kan det finnas behov av att ha information uppläst lokalt för bättre prestanda för att erbjuda användarvänliga funktioner i ett grafiskt gränssnitt, t.ex. “narrowing search”.

Rekommendationen i ett scenario där man utgår från cachad information är att göra ett anrop till adressbokens API från lokal Meddelandetjänst för att kontrollera/uppdatera adresseringsinformation innan meddelandet läggs på utgående Accesspunkt.

3.1 Paginering vid listningsoperationer

Då antalet funktionsadresser (och organisationer) kan bli väldigt stort över tid returneras listoperationer i batcher om 25 svar, s.k. paginering tillämpas.

En klient som vill läsa ner alla förekomster av en resurs behöver således anropa adressbokens API enligt:

antal anrop = totala antalet resurser i systemet / 25

Adressbokens API:er returnerar ett metadatafält “links.next” som indikerar om resultatet är en delmängd av hela mängden. Om länk “next” förekommer finnes ännu en resultatsida (“page”) att läsa ner från servern.

Nedan visas ett exempel (JSON) på metadatafältet “links” vid listning av systemets alla organisationer (resursnamn “organizations”). Genom att nyttja URL i metadata nedan behöver klienten inte själv känna till parametrar (som page[number] och page[size]) eftersom servern automatiskt kommer att skapa en ny “next”-länk för varje “page”.

GET /api/addresses

"links" : {
    "next" : "http://localhost:3081/api/organizations?page[number]=1&page[size]=25",
    "self" : "http://localhost:3081/api/organizations"
  }