REST til offentlige myndigheder

Yderligere dokumentation

https://datafordeler.dk/dataoversigt

http://grunddatamodel.datafordeler.dk/

Tjenesternes struktur og opbygning

Til offentlige myndigheder tilbydes et antal REST tjenester.

Tjenesterne er konstrueret sådan, at de alle anvender

• Input (query params) til brug for søgninger eller opslag:
  • Simple - Query params i form af enten PNR eller UID (opslag - personen er identificeret forud for opslaget).
  • Complete - Query params til søgninger. Her gives der mulighed for at søge på alle oplysninger.
• Output JSON Schema i form af (schemes er tilgængelig på datafordeler.dk )
  
  • Full - Alle oplysninger på en liste af personer inklusiv oplysninger på reference personer.
  • Medium - Alle oplysninger på en liste af personer. Reference angives kun med personnummer.
  • Small - Basale oplysninger, såsom personnumer, navn og adresse, på en liste af personer.
• Output med eller uden historik.
  • Current - kun aktuelle oplysninger, dvs. oplysninger med en aktuel virkningstid.
  • Aktuelle oplysninger og historiske oplysninger (Fremgår ikke af tjenestenavnet)
• Output med nul (0) til mange personer.
  • List - tjenester til offentlige myndigheder. Returnerer delmængde (sublist pr. page) af personer eller blot antal (count).

[Navngivning af metoder adskiller sig fra Datafordelerens retningslinjer (se datafordeler.dk), idet specifikationerne for CPR's tjenester er udarbejdet før udgivelse af retningslinjerne.]

Eksempel på count: count.json

PersonFull.json, PersonMedium.json og PersonSmall.json er hentet fra CPR's demodata (test04). Der er ikke garanti for, at eksemplerne over tid vil matche JSON schemes.

Tjenesternes output (oplysninger der videregives)

Teknisk dokumentation af tjenesternes output fremgår af tjenestens JSON scheme tilgængelig på datafordeler.dk samt datamodellen for Person på http://data.gov.dk/

Forskellen på Full og Medium tjenesterne er, at Full indeholder en række basale oplysninger på referencepersoner (forældre, ægtefælle mv.), mens Medium indeholder referencepersonens personnummer og uuid.

CprPersonFullSimple, CprPersonFullComplete, CprPersonMediumSimple og CprPersonMediumComplete

• Person (herunder personens status, fødselsregistrering, fødselsdato og køn)
• Beskyttelsesoplysninger
• Personnumre
• Navneoplysninger
• Statsborgerskabsoplysninger
• Civilstandsoplysninger
• Forælderoplysninger
• Børn
• Forældermyndighedsoplysninger
• Værgemål
• Forsvindinger
• UdrejseIndrejser
• Kontaktadresse
• Adresseoplysninger (herunder evt flyttepåbud)
• Kommunale forhold
• Valgoplysninger
• Folkekirkeoplysninger
• Kommunale notater

CprPersonSmallSimple og CprPersonSmallComplete

• Person (herunder personens status, fødselsregistrering, fødselsdato og køn)
• Beskyttelsesoplysninger
• Personnumre
• Navneoplysninger
• UdrejseIndrejser
• Adresseoplysninger

Kodeeksempel

Der er udviklet et kodeeksempel, der demonstrerer, hvordan der kan etableres forbindelse samt foretages opslag hhv. søgninger.

Læs mere - Kodeeksempel

Anvendelse af query params (parametre)

Query params anvendes i en HTTP GET request, og indgår således i HTTP requestens query string som field-value pairs.

Ønskes alle oplysninger på én person med pnr = 1111111111 anvendes PersonFullListSimple med query param pnr.personnumer.eq:

https://.../CprPersonFullSimple/1/rest/PersonFullListSimple?pnr.personnumer.eq=1111111111

Ønskes alle oplysninger på flere personer, som indentificeres ved anvendelse af personnummer, anvendes:

https://.../CprPersonFullSimple/1/rest/PersonFullListSimple?pnr.personnummer.wi=1111111111|2222222222|3333333333

Bemærk at pipe (|) anvendes som separator mellem hvert pnr.

CPR's tjenester på Datafordeleren understøtter ikke, at det samme query param field anvendes flere gange i samme query string.

Query params - navngivning af field

Query params tager udgangspunkt i CPR's domæne model - se http://data.gov.dk/model/

Eksempelvis indeholder Person klassen Personnummer, der indeholder attributten personnummer. Dvs. Person.Personnummer.personnummer.

Af praktiske og tekniske hensyn (bla. for at reducere størrelsen (size) på requesten) reduceres Person.Personnummer.personnummer til personnummer.pnr.

Query params - field operatorer

[Navngivning af operatorer adskiller sig fra Datafordelerens retningslinjer (se datafordeler.dk), idet specifikationerne for CPR's tjenester er udarbejdet før udgivelse af retningslinjerne.]

Hver query param tilføjes endvidere et subfix i form af et operatornavn. Eksempelvis

pnr.personnummer.eq

pnr.personnummer.wi

Der anvendes følgende operatorer:

[Navngivning af operatorer adskiller sig fra Datafordelerens retningslinjer (se datafordeler.dk), idet specifikationerne for CPR's tjenester er udarbejdet før udgivelse af retningslinjerne.]

Se dokumentation på datafordeler.dk for case sensitivity.

Ikke alle query params vil understøtte alle operatorer. Eksempelvis vil kun query params, hvor value kan parses til en integer eller date, kunne anvendes med gt (greather than).

Query params - value datatypes

Query params anvendes som nævnt på formen stat.cprlandekode.eq=5100&stat.status.eq=aktuel

En value vil i sagens natur altid være en string, men skal kunne parses/konverteres til en specifik datatype.

Der anvendes følgende datatyper:

Query params - søgninger med flere fields

Der er principielt ikke begrænsninger på, hvor mange query params der kan anvendes i en request. Dog har Datafordeleren en max limit size  i bytes på HTTP requestens størelse. HTTP requests med en query string større end max limit size vil resultere i en fejl. Se dokumentation herom på datafordeler.dk

Ved anvendelse af flere query params bygges en søgning på Datafordeleren, hvor query params sammensættes med en AND clause.

Der kan p.t. (juni 2018) ikke søges på null/empty values.

Eksempler:

/**
* 5100 er cpr landekode for Danmark
* 201 er kommunekoden for Allerød. Kommunekoden er en optimeret query param
* aktuel betyder, at det er den p.t. gældende registrering.
**/
query = "?"
		+ "&cadr.cprkommunekode.eq=201" 
		+ "&adropl.status.eq=aktuel"
		+ "&stat.status.eq=aktuel"
		+ "stat.cprlandekode.ne=5100"

//Svarer til
query = aktueltAdresseAlleroedKommune AND aktueltIkkeDanskStatsborger;

/**
* 201 er kommunekoden for Allerød
* 219 er kommunekoden for Hillerød
* Kommunekoden er en optimeret query param
* aktuel betyder, at det er den p.t. gældende registrering.
**/
query = "?"
		+ "adropl.status.eq=aktuel"
		+ "&cadr.cprkommunekode.wi=201|219"
		+ "&cadr.vejadresseringsnavn.eq=Hammersholt%20Byvej";

//Svarer til
query = (aktuelAdresseAlleroedKommune OR aktuelAdresseHilleroedKommune) AND aktuelAdresseVejHammersholtByvej;

/**
* Status bopael_i_danmark eller bopael_i_danmark_hoej_vejkode betyder, at personen har bopæl i en dansk kommune. Statusoplysningen er ikke histroisk, hvorfor det ikke er nødvendigt at anvende i form af aktuel, histroisk mv.
* count=true betyder, at der kun returneres antal.
**/
query = "?"
		+ "person.foedselsdato.lt=2008-01-01"
		+ "&person.foedselsdato.ge=2007-01-01"
		+ "&person.status.wi=bopael_i_danmark|bopael_i_danmark_hoej_vejkode"
		+ "&count=true

//Vil returnere ANTAL personer, som er født i 2007 og som har bopæl i en dansk kommune

/**
* 201 er kommunekoden for Allerød
* Vejkoden 999 er fiktiv
* Kombinationen af en vejkode og kommunekode udgør en unik identifikation af en vej.
* count=true betyder, at der kun returneres antal.
**/
query = "?"
		+ "adropl.status.eq=aktuel"
		+ "&cadr.cprkommunekode.eq=201"
		+ "&cadr.cprvejkode.eq=999"
		+ "&cadr.husnummer.eq=004"
		+ "&count=true";

//Vil returnere ANTAL personer på vejen med vejkode 999 med husnummer 4
//Bemærk, at hvis det er en etageejendom vil dette eksempel returnere antal personer i alle lejligheder.
//Bemærk også, at husnr altid angives med foranstillede 0'er, således at et husnr er opbygget af 3 cifre og optionelt et bogstav efterfølgende. Husnr 041 svarer til nr. 41, 004 til 4 , 009A til 9A.

Paging og count

Se detaljeret dokumentation om paging og count på datafordeler.dk

Det bemærkes, at retursvaret fra datafordeleren ikke indeholder information om count, page og pagesize. Det er således op til anvenderen selv at holde styr på, hvilken page der returneres.

Idet count ikke indgår i retursvaret kan det overvejes først at kalde tjenesten med param count=true, hvorved retursvaret kun indeholder count. Derved kan det regnes ud, hvor mange gange tjenesten skal kaldes, således at alle personer, der opfylder søgekriterierne, returneres. Dvs. antal_kald = Math.ceil(count / pagesize). Det bemærkes, at en tjeneste kan kaldes asynkront, hvorved den samlede svartid givetvis vill kunne forbedres.

Count

Hvis det ønskes oplyst hvor mange personer, der vil blive returneret i en søgning, kan param count=true anvendes.

Derved returneres kun antal entiteter/personer, der opfylder anvendt søgekriterie.

Paging

Default page size er sat til 20. Dvs. hver request vil højst returnere 20 personer på hver page. Der kan være 0 til mange pages.

Alle kald til tjenesten med en søgning (parametre), der resulterer i en response på mere end 20 personer, og som kaldes uden page angivelse, vil således returnere første page med en liste på 20 personer. Tjenesten vil derfor skulle kaldes flere gange (svarende til antal pages), hvor page forøges med 1 hver gang, hvis der ønskes data retur på alle personer, som opfylder søgningen. Hvis en page indeholder færre personer (herunder 0) end pagesize, vil det være sidste side.

F.eks. vil

https://.../rest/PersonFullListSimple?pnr.personnummer.wi=1111111111|2222222222|3333333333&pagesize=1&page=2

maksimalt returnere en liste med ét objekt/én person (pagesize=1). Bemærk, at der ikke er garanti for, at det er personen med pnr 2222222222 (Bemærk: Første page er tilsyneladende 1, ikke 0 - læs mere herom på datafordeler.dk).

For det første er der ikke garanti for i hvilken rækkefølge en liste af parametre behandles på Datafordeleren. For det andet kan det være, at der ikke findes en person med pnr = 1111111111 , hvorved personen med pnr = 2222222222 (hvis denne person findes) vil fremgå på første page.

Principielt kan data tillige blive opdateret, mens der itereres gennem pages. Det betyder, at når der itereres gennem pages - idet hvert kald til tjenesten er stateless - er der ikke garanti for, at hver page ikke returnerer personer, der ikke tidligere er blevet returneret på en anden page. Ligesom der ikke er garanti for, at der reelt returneres alle personer, der opfylder søgekriterierne. Hvis der skal være garanti herfor, skal pagesize sættes til et heltal større eller lig med count (max pagesize kendes ikke). 

I praksis er risikoen dog meget begrænset, idet der p.t. (juni 2018) kun indlæses data én gang i døgnet, og der ikke er stor sandsynlighed for, at der søges på personer, der netop opdateres.

Anvendere kan reducere risikoen ved at kalde tjenesten med  count = true før og efter, hvorefter resultatet sammenlignes.

Kendte begrænsninger

CPR-kontoret er blevet opmærksom på en række begrænsninger i tjenesterne. Begrænsningerne vil løbende blive søgt afhjulpet.

Count. Total antal entiteter, dvs. antal personer, der opfylder anvendte søge kriterier/query params, indgår ikke i response. Anvendere kan med fordel kalde tjenesten først med count=true.

Aktuel page. Aktuel page fremgår ikke af response. Anvendere skal således selv holde styr på hvilken page, som er requested.

Antal pages. Antal pages fremgår ikke af response. Anvendere kan derfor selv beregne antal pages ved at anvende count=true og anvendt pagesize.

Default pagesize. Default Pagesize fremgår ikke af response. Default pagesize fremgår af dokumentation på datafordeler.dk (den 1. maj 2018 var denne sat til 20).

Aktuel pagesize. Antal entiteter, dvs. personer, der returneres fremgår kun inddirekte i responsen. Antal personer kan fastsættes ud fra længden på listen (array) af personer.

Iteration gennem pages. Hvis en anvender ønsker at "bladre", dvs. iterere over pages, vil det give en samlet langsom svartid.

Flere nær-samtidige (asynkrone) requests. Det er muligt at foretage en ny request uden at vente på response fra forrige request. Derved kan den samlede svartid ved at "bladre" gennem pages reduceres væsentligt. Imidlertid kan det i praksis medføre timeouts.

Opslag - Simple query params

Der er seks tjenester målrettet offentlige myndigheder, der kan anvendes til opslag, hvis personens/personernes personnummer eller UUID er kendt.

Navngivningen af query params tager udgangspunkt i CPR's domænemodel. Følgende query params kan benyttes (paramsForTabelSimple.csv):

Svartider / Performance ved søgninger

Bemærk: Ved søgninger bør der altid altid indgå mindst ét query param, der er anført som optimeret.

Ved søgninger uden brug af optimeret query params, må der forventes lange svartider.

Søgninger - Complete query params

Navngivningen af query params tager udgangspunkt i CPR's domænemodel, se http://data.gov.dk/model/ og anvendere bør derfor orientere sig i domænemodellen for at forstå sammenhængen mellem query params.

Følgende query params kan benyttes (paramsForTabelComplete.csv):

_{(Sorter ved at klikke på kolonne overskrifter)}