REST til offentlige myndigheder

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



TjenesteMetodeEksempel JSON outputListOpslagSøgningAktuelle oplysningerAktuelle og historiske oplysninger
1CprPersonFullSimplePersonFullListSimplePersonFull.jsonListSimple

Aktuelle og historiske
2CprPersonFullSimplePersonFullCurrentListSimplePersonFull.jsonListSimple
Current
3CprPersonFullCompletePersonFullListComplete  PersonFull.jsonList
Complete
Aktuelle og historiske
4CprPersonFullCompletePersonFullCurrentListComplete PersonFull.jsonList
CompleteCurrent
5CprPersonMediumSimplePersonMediumListSimplePersonMedium.jsonListSimple

Aktuelle og historiske
6CprPersonMediumSimplePersonMediumCurrentListSimplePersonMedium.jsonListSimple
Current
7CprPersonMediumCompletePersonMediumListCompletePersonMedium.jsonList
Complete
Aktuelle og historiske
8CprPersonMediumCompletePersonMediumCurrentListCompletePersonMedium.jsonList
CompleteCurrent
9CprPersonSmallSimplePersonSmallListSimplePersonSmall.jsonListSimple

Aktuelle og historiske
10CprPersonSmallSimplePersonSmallCurrentListSimplePersonSmall.jsonListSimple
Current
11CprPersonSmallCompletePersonSmallListCompletePersonSmall.jsonList
Complete
Aktuelle og historiske
12CprPersonSmallCompletePersonSmallCurrentListCompletePersonSmall.jsonList
CompleteCurrent

[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.jsonPersonMedium.json og PersonSmall.json er hentet fra CPR's demodata (test04) den 14. februar 2020. Der er ikke garanti for, at eksemplerne over tid vil matche JSON schermes.

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 anvender GET parametre i en HTTP 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:


Ønskes alle oplysninger på flere personer anvendes:


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.


Der anvendes følgende operatorer:

#Operator navnSQL OperatorBetydning
1eq=equal
2ne<> or !=not equal
3gt>greater than
4ge>=greater than or equal to
5lt<less than
6le<=less than or equal to
7wiinThe result is "true" if the left-hand expression's result is equal to any of the right-hand expressions.
8contLike

The LIKE expression returns true if the string matches the supplied pattern.

The supplied pattern is always % as prefix and subfix. The percent sign (%) matches any sequence of zero or more characters.

Effectively this can be compared to str.indexOf('value')>-1 or str.contains('value')

[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 skal kunne 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:

DatatypeFormat
String

String [.*]

Se dokumentation for url encoding på datafordeler.dk

Se dokumentation om case sensitivity på datafordeler.dk

IntegerEt heltal [0-9]
Boolean

true

false

Date

ISO 8601

Se dokumentation for date and time formats på datafordeler.dk

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:

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

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 1, ikke 0).

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:




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:

(Sorter ved at klikke på kolonne overskrifter)