API Design (V2)
- 1 Introduktion
- 2 Designbeslutninger
- 2.1 UUID’er
- 2.2 Paginering på listeudtræk
- 2.3 Centreret omkring rod-aggregater
- 2.4 Delta-feed
- 2.4.1 Ændrede registreringer
- 2.4.2 Slettede registreringer
- 2.5 Krydsreferencer
- 2.5.1 Eksempel
- 2.6 Særskilte læse- og skrivemodeller (de er ikke kopier af hinanden)
- 2.6.1 Krydsreferencer
- 2.6.1.1 Eksempel - LÆS
- 2.6.1.2 Eksempel - SKRIV
- 2.6.2 Beregnede statusfelter
- 2.6.3 Loginformationer
- 2.6.1 Krydsreferencer
- 2.7 Informationen findes der hvor den registreres (og kan opdateres)
- 2.8 Opdateringer
- 2.8.1 Obligatoriske og valgfrie felter
- 2.8.2 PUT
- 2.8.3 PATCH
- 2.8.3.1 Hvilket PATCH format anvendes
- 2.8.3.2 Eksempler
- 2.8.3.2.1 Scenario 1: Opdatering af “name”
- 2.8.3.2.2 Scenario 2: Opdatering af “localId”
- 2.8.3.2.3 Scenario 3: Opdatering af “name” og parentUuid
- 2.8.3.2.4 Scenario 4: Nulstilling af sektioner/felter
- 2.8.4 Forretningsreglerne er stadig gældende
- 3 Vejledning til rettighedshavere
- 4 Swagger
Introduktion
Arbejdet med version 2 af KITOS API blev igangsat i foråret 2021 og udvikles i fem etaper:
Etape 1: IT-Systemer (i kataloget) og Snitflader https://os2web.atlassian.net/browse/KITOSUDV-63
Etape 2: IT-Systemer i kommunen https://os2web.atlassian.net/browse/KITOSUDV-1928
Etape 3: Databehandling KITOSUDV-1949: Som kommunebruger vil jeg - med API adgang - kunne administrere mine registreringer under modulet "Databehandling"Leveret
Etape 4: Kontrakter https://os2web.atlassian.net/browse/KITOSUDV-1950
Etape 5: Delta-Feed https://os2web.atlassian.net/browse/KITOSUDV-2041
Etape 6: PATCH i høj opløsning KITOSUDV-2358: PATCH på API V2Leveret
Formålet med arbejdet er at stille et funktionelt og komplet API til rådighed hvorigennem interessenter, rettighedshavere, leverandører og kommuner kan læse/skrive data fra/til KITOS samtidig med at forretningsreglerne overholdes og stamdataene derfor forbliver anvendelige.
Version 2 skrives fra bunden af og i tæt samarbejde med de anvendende interessenter.
Udfases version 1?
Ja version 1 er udfaset og ikke længere tilgængeligt med JWT KITOSUDV-3133: Ekstern adgang til API V1 lukkes (1. december 2022) - OBS: Udskudt til 1. marts 2023Leveret
Designbeslutninger
API’et udvikles med afsæt i de logiske grupperinger (moduler/rodaggregater) der eksisterer i KITOS. Data udstilles via et REST API, hvorigennem man i første omgang vil kunne benytte sig af følgende HTTP verber:
POST: Oprettelse af nye ressourcer
GET: Hente eksisterende ressourcer
PUT: Eksisterende version af ressource opdateres med nye data
PATCH: Delvis opdatering af en eksisterende ressource
DELETE: Ressourcen nedlægges
Grundlæggende gives der adgang til de samme data som brugeren i øvrigt har adgang til via KITOS UI. Forskellene opstår ved inspektion af de enkelte ressourcer, hvor UI i nogle tilfælde kombinerer data fra flere moduler (selv under navngivne modulsider) så vil API’et i bred udstrækning tillade at det samme information findes men kun der hvor det registreres.
UUID’er
I KITOS API vil alle ressourcer være tildelt en UUID, der er garanteret unik og garanteret stabil uanset ændringer i den bagvedliggende struktur. I Version 1 har man typisk anvendt “Id” feltet på ressourcerne - et felt der primært er tiltænkt databasens relationsmodel, men som, af mangel på bedre, har været anvendt som identifikation på ressourcer trukket ud via API’et. Dette ændres der på i Version 2 hvor kun UUID er gyldigt som identifikation for ressourcer i KITOS.
Paginering på listeudtræk
På de API endpoints hvor der tilbydes listeudtræk skal man forholde sig til paginering via følgende query parametre:
pageSize [1-(250| Ubegrænset)]: Antal resultater pr. svar.
Hvis det ikke defineres, vil Swagger dokumentation angive standardværdien. Det fremgår samtidigt her hvorvidt maksimal pageSize er 250 eller ubegrænset.
page: [0-Int.MaxValue]: Offset i resultaterne. Offset vil være (pageSize * page)
Hvis det ikke defineres vil KITOS bruge 0 som standardværdi
Eksempel:
HTTP GET https://kitos.dk/api/v2/it-systems?page=0&pageSize=50
Bemærk: Udelades pagineringsparametre vil KITOS benytte standardværdierne fra API dokumentationen. For endpoints hvor pageSize er ubegrænset, vil en udeladt værdi resultere i at hele resultatsættet returneres i et enkelt kald.
Centreret omkring rod-aggregater
Rodaggregaterne (modulerne) i KITOS vil være omdrejningspunktet for KITOS API’et herunder:
IT-Systemer fra kataloget (stamdata)
IT-Systemer i organisationen (lokale registreringer i forlængelse af stamdata fra kataloget)
Snitflader
Kontrakter
Databehandling
Herudover vil der være en række understøttende API’er der typisk leverer læse-adgang til en række tilknyttede ressourcetyper herunder fx:
Udfaldsrum
Organisationer
Brugere i organisationen
Målsætningen er ikke, at man skal kunne alt det man kan i hele KITOS UI (administration af udfaldsrum f.eks.), men indenfor rodaggregaterne skal man kunne hente og skrive alt hvad man ellers er i stand til via UI, uden at det nødvendigvis er på samme form.
Delta-feed
Ændrede registreringer
For hver af de redigérbare rod-aggregater er det muligt at fremsøge ændrede registreringer siden et givent UTC timestamp.
HTTP GET https://kitos.dk/api/v2/data-processing-registrations?changedSinceGtEq=2021-09-27T11%3A50%3A00.021Z&page=0&pageSize=100
Ovenstående eksempel henter de senest 100 ændrede registreringer i modulet databehandling siden den 27. september 2021 kl. ca. 11:50:00 UTC. Når parameteren changedSinceGtEq
anvendes, er resultaterne sorteret (stigende) ift. feltet LastModified.
Slettede registreringer
For at hente information om registreringer, som er slettet siden et givent UTC timestamp, er der udstillet et specifikt endpoint til at hente denne information.
https://kitos.dk/api/v2/delta-feed/deleted-entities?entityType=DataProcessingRegistration&deletedSinceUTC=2021-09-27T11%3A50%3A00.153Z&page=0&pageSize=100
Ovenstående url henter identiteten på de seneste 100 slettede registreringer i modulet “databehandling” siden 27. september 2021 kl. ca. 11:50:00 UTC
Krydsreferencer
Når en ressource refererer til en anden ressource - f.eks. en snitflade der refererer et udstillersystem - så vil KITOS API tilføje en krydsreference. En krydsreference er en simpel datastype, der (som minimum) indeholder navn (name) og en id (uuid). Detaljeret information kan hernæst findes via det REST API, der findes for den krydsrefererede type.
Eksempel
Fra snitflade API’et returneres en krydsreference til udstillersystemet:
For at hente information om udstillersystemet tilgås API’et for IT-Systemer (stamdata):
Ønsker man ikke at hente systeminformationen ud har man dog stadig et navn (meningsfuldt for mennesker) såvel som en UUID, der benyttes iftm. senere operationer på API’et.
Særskilte læse- og skrivemodeller (de er ikke kopier af hinanden)
I KITOS API V2 er læse- og skrivemodellerne for den samme ressource ikke éns.
Overordnet set tilstræbes det at felter og datatyper er de samme for både læse og skrivemodeller, men der vil være situationer, hvor de vil adskille sig. Eksempler på de oftest forekommende er:
Krydsreferencer
I skrivemodellerne vil feltet typisk navngives med endelsen “Uuid” og datatypen vil være en UUID (JSON String)
I læsemodellerne vil feltet ikke have endelsen “Uuid” og vil typisk være en kompleks type indeholdende feltet Uuid
og Name
. For krydsreferencer til organisationer, vil der typisk også være et Cvr
felt.
Eksempel - LÆS
Eksempel - SKRIV
Beregnede statusfelter
KITOS udstiller i visse tilfælde en samlet status for registreringen (Kontrakt, Systemanvendelse og Databehandlinger), og denne samlede status beregnes på baggrund af registreringerne i andre felter, f.eks. opsigelsesdato på en kontrakt) .Feltet der viser den samlede status vil derfor ikke være synligt på skrivemodellerne men kun på læsemodellerne.
Loginformationer
Informationer der logges af KITOS som f.eks. CreatedBy
og LastModified
udstilles kun på læsemodellerne.
Informationen findes der hvor den registreres (og kan opdateres)
I KITOS UI vil man typisk kunne finde den samme information flere steder. Dette kan give mening for at lette brugervenligheden og overblikket i en UI sammenhæng men for API brugere er det vigtigt at stamdata findes det samme sted hver gang.
Et eksempel herpå kunne være:
Udstillede snitflader: I UI vises dette både på IT-Systemet i kommunen samt på stamdata fra kataloget. Logisk set er snitfladen knyttet til stamdata så i API vil udstillede snitflader altså findes ved at trække information ud fra IT-System-stamdata hvortil der vil være en krydsreference i udtrækket fra kommunens egne data.
Et andet eksempel kunne være systemhierarki, der i dag vises på IT-Systemet i kommunen. Ligesom udstillede snitflader registreres denne information på stamdata, hvorfor den også skal hentes her. Hierarkiet dannes via udtræk af stamdata og opbygning af hierarki via “ParentSystem”.
Tilsvarende eksempler kunne beskrives for andre scenarier men strategien eksisterer for at gøre det tydeligt hvor data opstår og hvor det efterfølgende kan vedligeholdes.
Opdateringer
Modsat Version 1 tilbyder Version 2 også skrivning af data. Afhængigt af rettigheder tilbydes:
Oprettelse af nye ressourcer
Rettelse af eksisterende ressourcer
Nedlæggelse (sletning/deaktivering) af eksisterende ressourcer.
Obligatoriske og valgfrie felter
Ifm. oprettelse og tilretning, vil man i API dokumentationen blive præsenteret for felter der enten er obligatoriske eller valgfrie (markeret med optional) i swagger:
Obligatoriske felter SKAL altid være til stede ifm. enten PUT eller POST. Valgfrie felter MÅ gerne være til stede. Såfremt de ikke leveres, nulstilles de af KITOS ifm. POST eller PUT.
PUT
I PUT leveres alt data til den nye version af ressourcen. Dette betyder at udfylder man ikke et valgfrit felt i json dokumentet der sendes ifm. PUT, så nulstiller KITOS data for dette felt. Da data kan have været opdateret i KITOS anbefales det derfor at skrive ændringer via API via følgende protokol:
GET ressourcen, der skal ændres via GET api/v2/{ressource-type}/{uuid}
Flet data fra den seneste version fra KITOS med ændringer der skal skrives
PUT resultatet af fletningen.
PATCH
Når PATCH anvendes er det for at muliggøre opdatering af en delmængde af ressourcen dvs. man skal i denne sammenhæng ikke levere en fuld opdatering men kan nøjes med at opdatere den del af data som er relevant.
Hvilket PATCH format anvendes
KITOS' (forudsat KITOSUDV-2358: PATCH på API V2Leveret ) understøtter PATCH jf. JSON Merge Patch standarden: RFC 7396: JSON Merge Patch
Eksempler
Udgangspunktet er følgende, komplette, datakontrakt:
Scenario 1: Opdatering af “name”
Ovenstående payload vil resultere i en opdatering af “name” og kun “name”.
Scenario 2: Opdatering af “localId”
For localId bemærkes, at dette ligger på en sektion “general”, så dette objekt skal medtages i request inklusive alle de felter der skal opdateres herpå:
I ovenstående opdateres localId
mens enabled
ikke ændres fra sin nuværende værdi.
Scenario 3: Opdatering af “name” og parentUuid
Scenario 4: Nulstilling af sektioner/felter
Såfremt feltet/sektioen optræder i input-data, vil det blive evalueret, så hvis der f.eks. leveres “null” til “general”, så vil det blive opfattet som “nulstilling af general-sektionen og alle data herunder”.
Forretningsreglerne er stadig gældende
De forretningsregler/begrænsninger man er vant til via KITOS UI er stadig gældende ifm. anvendelse af API’et.
Vejledning til rettighedshavere
Der er udarbejdet særlige endpoints til rettighedshavere. Se særskilt vejledning her: https://os2web.atlassian.net/wiki/spaces/KITOS/pages/2059796674
Swagger
Se venligst Swagger dokumentation