Page Comparison

...

Varsling om lukning

Adgang til API V1

...

er lukket

❗ ❗ OBS: Lukningen er udskudt til 1. marts 2023.

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.

Da API-initiativet blev startet primo 2018, blev det besluttet, at man ville udstille de eksisterende REST APIer til andre klienter end UI - såkaldte API klienter.

For at tilgodese disse API klienter, blev der udviklet en Json Web Token baseret autentifikationsmodel (herefter: JWT) , hvormed en bruger kan tilgå KITOS' API. Adgang med JWT giver de samme rettigheder (på brugeniveau), som havde man programmeret sin API klient baseret på cookies (hvilket nogle kommuner allerede har). En midlertidig undtagelse fra denne regel beskrives i “Kun adgang til læseoperationer”.

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”).

Man kan derfor i første omgang ikke ændre på data i KITOS uden om UI.

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.:

/odata/itsystems

Med denne URI i hånden, kan der foretages OData queries på den delmænge af ressourcen, som brugeren har lov til at se i kontekst af de rettigheder brugeren har på tværs af dennes organisationsroller.

Det betyder, at hvis man f.eks. er almindelig bruger i én (eller flere) kommune(r), så består delmængden af:

• Alle IT-systemer, som er lokalt oprettet i de kommuner som brugeren har roller i.

• Alle IT-systemer i andre organisationer, som er markeret som “Offentlig”.

Ønsker man at få begrænset udfaldsrummet til en specifik kommunes data er det derfor tilrådeligt at benytte de mere specialiserede endpoints, som afgrænser data fra starten af.

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

Se venligst Swagger dokumentation

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.

Det skaber en række problemer ift. at begrænse hvad man kan trække ud af en forespørgsel. Man kan f.eks., ved brug af $expand, grave information frem, som man ellers ikke ville være autoriseret til at se. Derudover, vil man ofte få mere tilbage end man “havde lyst til”, hvilket har indflydelse på svartiden. Udover de nævnte udfordringer, vil en ændring i den bagvedliggende model også automatisk påvirke alle klienter (før var det kun UI), og det skaber nogle unødvendige bindinger.

I det fremadrettede arbejde med KITOS, vil der i høj grad være fokus på ikke at aflevere mere data end “nødvendigt”, hvilket både løser rettighedsproblemet og de ydelsesrelaterede udfordringer.

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 eksterne 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.

Som eksempel kan man tage:

/odata/Organizations(1)/ItSystems

Ved blot at se på ovenstående URI, kunne man fristes til at tro, at man ville få ItSystemerne for organisation '1' tilbage. Det man får tilbage er:

• Alle IT Systemer, som man har lov til at se i organisation '1'

• Hvis man er bruger i en kommune eller global admin, får man også IT Systemer fra andre organisationer som er delt dvs. “Synlighed=Offentlig”

Årsagen hertil findes sandsynligvis i en konkret use case, man har forsøgt løst for UI, men ved at se på URI alene, virker resultatsættet umiddelbart forkert.

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å:

• I samarbejde med brugerne at specificere og udvikle konkrete eksterne API-snit, hvor intentionen fra starten af er tilgang fra en tilstandsløs klient, der ikke forventer data trukket ud efter implicitte regler, der skal understøtte én bestemt klients use case.

...

• 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.API V2 anvendes og vedligeholdes fremadrettetAPI Design (V2)