OBS: Denne side beskriver historik og generelle ting omkring Version 1 af API’et. Søger du information om Version 2, bedes du besøge siden API Version 2
Historik
OS2Kitos applikationen (herefter KITOS) består overordnet set af en Angular JS applikation (herefter: UI) der kommunikerer med en backend via en række REST APIer.
...
JWT tokens er den eneste autentifikationsform, der bør anvendes af API klienter, idét man herved kun får adgang til det “officielle” API (det der ydes support på).
Kun adgang til læseoperationer
Såfremt man anvender APIet som tiltænkt dvs. med JWT, får man kun adgang til operationer, der ikke ændrer på data (se “Kendte problemer”).
...
Konkrete behov for API adgang til ændring af data fremsendes til Kitos Sekretariatet, hvor en eventuel udviklingsopgave vil blive formuleret og prioriteret (se “Hvad kan I forvente af KITOS API fremadrettet?”).
Begreber og tilgange
KITOS' REST APIer er realiseret via to forskellige designs.
Klassiske REST API
De klassiske REST API’er findes under ruterne /api/* og forholdet mellem URI og operationer tilnærmer sig de gængse retningslinjer.
API’erne returnerer DTO objekter der repræsenterer en abstraktion af den bagvedliggende datamodel.
OData (V4) REST API
Under stien /odata/* findes KITOS' OData baserede REST APIer. Udover specialiserede endpoints indeholder de fleste et “root query” endpoint som typisk findes på “collection” URI dvs f.eks.:
...
Indenfor denne delmængde kan man så anvende standard OData queries til f.eks. at filtrere ($filter), sortere ($orderBy) og begrænse returmængden ($top,$skip).
Swagger dokumentation
Den interaktive Swagger dokumentation for KITOS API findes her: https://kitos.dk/swagger.
Med en JWT i hånden kan de forskellige API endpoints kaldes direkte fra dokumentationen via funktionaliteten “Try it out” som vist nedenfor.
...
Eksempler på anvendelse
KITOS APIets testgrundlag udvikles løbende og vedligeholdes her: https://github.com/Strongminds/kitos/tree/master/Tests.Integration.Presentation.Web(seneste udviklingsversion) og her: https://github.com/os2kitos/kitos/tree/master/Tests.Integration.Presentation.Web(senest frigivne version).
Her findes eksempler på interaktion med KITOS API med hhv. cookie (forudsætninger for vores tests) og via JWT (via det officielle API).
Kendte problemer
Følgende problemer er identificeret og vil blive løst løbende i forbindelse med videreudviklingen af KITOS.
OData-API’erne udstiller domæne/database modellen 1-1
Ved tilgang til KITOS API via OData API, vil KITOS aflevere data i den eksakte form, som den er repræsenteret i den bagvedliggende datamodel.
...
Da en stor del af KITOS UI baserer sig på de faciliteter, der er årsag til ovennævnte problemer, vil de eksisterende OData APIer i første omgang bestå i sin nuværende form men vil langsomt blive flyttet væk fra det interne API og kun kunne anvendes af UI.
Endpoints returnerer bredere forspørgsler end man tror
Da KITOS API historisk set kun har haft én kunde (UI) er nogle endpoints hårdere koblet til en konkret use-case end hvad der er hensigtsmæssigt.
...
I det videre arbejde med KITOS vil vi sikre, at API endpoints undgår implicitte regler, og tydeligt kommunikerer deres intention. I overgangsfasen vil vi, hvor det er muligt, sikre, at swagger dokumentationen beskriver det potentielle indhold af resultatsættet.
Hvad kan i forvente af KITOS API fremadrettet?
For at sikre, at KITOS API udvikler sig i den rigtige retning, vil der fremadrettet blive holdt fokus på:
...
At overvåge anvendelsen af det nuværende API, således at vi nemmere kan fokusere indsatsen på de områder der anvendes mest.
At versionere nye API endpoints.
Vær med til at præge udviklingen
For at sikre, at KITOS API udvikler sig i den rigtige retning, er det vigtigt, at eventuelle problemer, spørgsmål eller ønsker rettes til KITOS Sekretariatet. I samråd med leverandøren, vil konkrete tiltag herefter blive formuleret, vurderet og prioriteret.