Page Comparison

OBS: Denne side vedrører kun version 2 af API’et. Søger du generel information eller version 1 information bedes du læse API Design (V1)

...

• Etape 1: IT-Systemer (i kataloget) og Snitfladerhttps://os2web.atlassian.net/browse/

  Jira Legacy
  server System JIRA serverId 277b2c09-df07-3469-bccc-a66f399c29a7 key KITOSUDV-63

• Etape 2: IT-Systemer i kommunen https://os2web.atlassian.net/browse/

  Jira Legacy
  server System JIRA serverId 277b2c09-df07-3469-bccc-a66f399c29a7 key KITOSUDV-1928

• Etape 3: Databehandling https://os2web.atlassian.net/browse/

  Jira Legacy
  server System JIRA serverId 277b2c09-df07-3469-bccc-a66f399c29a7 key KITOSUDV-1949

• Etape 4: Kontrakter https://os2web.atlassian.net/browse/

  Jira Legacy
  server System JIRA serverId 277b2c09-df07-3469-bccc-a66f399c29a7 key KITOSUDV-1950

• Etape 5: Delta-Feed https://os2web.atlassian.net/browse/

  Jira Legacy
  server System JIRA serverId 277b2c09-df07-3469-bccc-a66f399c29a7 key KITOSUDV-2041

• Etape 6: PATCH i høj opløsning https://os2web.atlassian.net/browse/

  Jira Legacy
  server System JIRA serverId 277b2c09-df07-3469-bccc-a66f399c29a7 key KITOSUDV-2358

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?

Version 1 af API’et vil, på sigt, blive udfaset i den forstand at det ikke længere bliver muligt at tilgå det med KITOS token. Før dette kan ske skal Version 2 dog kunne opfylde de integrationsbehov der findes, og udfasningen vil blive meldt ud i god tid.Ja version 1 er udfaset og ikke længere tilgængeligt med JWT

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

  Bemærk: Indtil https://os2web.atlassian.net/browse/KITOSUDV-2358 er leveret, vil “opløsningen” af PATCH opdateringer være grovkornet. Se mere herom i sektionen https://os2web.atlassian.net/wiki/spaces/KITOS/pages/2059599873/API+Design+V2#PUT-og-PATCH .

• DELETE: Ressourcen nedlægges

...

På de API endpoints hvor der tilbydes listeudtræk skal man forholde sig til paginering via følgende query parametre:

• pageSize [1-(100 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 100 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

...

Målsætningen er ikke, at man skal kunne alt det man kan i hele KITOSU 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.

...

Ø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 Cvrfelt.

Eksempel - LÆS

{
  ...
  ..
	"systemContext": {
		"uuid": "00000000-0000-0000-0000-000000000000",
		"name": "string"
	},
	"organizationContext": {
		"cvr": "string",
		"uuid": "00000000-0000-0000-0000-000000000000",
		"name": "string"
	}
  ...
  ..
}

Eksempel - SKRIV

{
  "systemUuid": "00000000-0000-0000-0000-000000000000",
  "organizationUuid": "00000000-0000-0000-0000-000000000000",
}

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)

...

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 første omgang tilbydes rettelser via anvendelse af PUT og i begrænset omfang via PATCH. 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 relavantrelevant.

Hvilket PATCH format anvendes

KITOS' (forudsat https://os2web.atlassian.net/browse/

Begrænsninger i PATCH

Indtil https://os2web.atlassian.net/browse/KITOSUDV-2358 er løst, tilbydes PATCH med begrænset opløsning, hvor valgfriheden tilbydes på “rod-niveau”. Dette er eksemplificeret nedenfor:

Eksempler

Udgangspunktet er følgende, komplette, datakontrakt:

...

Scenario 1: Opdatering af “name”

...

PATCH /api/v2/{ressouce}/{uuid}
{
  "name": "a new name"
}

...

For localId bemærkes, at dette ligger på en sektion “general”, men at det ligger på linje med andre felter som forventes leveret i samme request. Derfor vil følgende request være korrektså dette objekt skal medtages i request inklusive alle de felter der skal opdateres herpå:

PATCH /api/v2/{ressouce}/{uuid}
{
  "general" : {
      "enabled": {current_enabled_state_fetched_Before_patch},
      "localId": "a new local id"
  }
}

Udelades “enabled” fra requestet, vil KITOS nulstille dette felt til standardværdienI ovenstående opdateres localId mens enabled ikke ændres fra sin nuværende værdi.

Scenario 3: Opdatering af “name” og parentUuid

...

PATCH /api/v2/{ressouce}/{uuid}
{
  "name": "a new name",
  "parentUuid" : "B47C7EF7-E7B3-4FD5-B7B8-B4C4CA78BBD9"
}

Derved vil kun “name” og “parentUuid” blive opdateret, og sektionen “general”, og alle data herunder, vil forblive uberørt.

Scenario 4: Nulstilling af sektioner/felter

Såfremt feltet optræder på rodniveau/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”.

...