Denne side beskriver adgangen til og den tekniske distribution af GraphQL, som er gældende for alle registre på Datafordeleren, der udstiller data med GraphQL.

Siden beskriver hvordan anvendere på Datafordeleren kan benytte GraphQL-tjenesterne til at hente tabulære data fra registrene.

Begreber

På siderne om GraphQL bruges nedenstående begreber. Bemærk at begreberne også bliver yderligere forklaret med eksempler på siderne.

Hvad er GraphQL?

GraphQL er et moderne API-sprog, der gør det muligt at hente data på en effektiv og fleksibel måde. GraphQL giver mulighed for at hente præcis de oplysninger, du som anvender skal bruge. GraphQL-tjenesterne er derfor velegnede når du ønsker at hente mindre datamængder og ikke nødvendigvis ønsker at postprocessere data efterfølgende.

Du kan bruge GraphQL-tjenesterne ved at sende en forespørgsel, der beskriver du data de ønsker, til Datafordeleren, hvorefter serveren kun svarer med de specifikke data, der blev anmodet om. Dette kan du blandt andet gøre gennem en desktop applikation eller gennem browseren ved brug af en browser-extension.

Med GraphQL kan du definere hvilke datafelter du ønsker returneret. Dette betyder, at du kun modtager de oplysninger, du har brug for. Det kan dermed forbedre svartiden for tjenesterne og reducere mængden af data, som overføres.

Yderligere information om GraphQL kan findes på graphql.org.

Måden du bruger GraphQL-tjenesterne på, er ved at sende en såkaldt query til et af Datafordelerens GraphQL-endepunkter. En query er anvendernes måde at definere hvilke data du ønsker at hente.

Et eksempel på en query mod tjenesten https://graphql.datafordeler.dk/BBR/v1 kan ses nedenfor.

GraphQL-queries fungerer således:

• Entitet (beskrevet i afsnit 2.2)
  • En query skal specificere hvilken entitet den omhandler.
  • Eksemplet ovenfor viser en query for entiteten BBR_Bygning fra BBR.
• Tjeneste (beskrevet i afsnit 2.3)
  • En query skal sendes til en GraphQL-tjeneste, der indeholder den pågældende entitet, som et GET- eller POST-request.
• Standardfiltre (beskrevet i afsnit 2.4)
  • En query kan indeholde standardfiltre der filtrerer data.
  • Eksemplet ovenfor indeholder to standardfiltre: lighedsoperator (eq: "0550") på kommunekode og (eq: "6") på status.
• Geometriske filtre (beskrevet i afsnit 2.5)
  • En query kan indeholde geometriske filtre, der filtrerer data på baggrund af geometri-felter.
• Bitemporale filtre (beskrevet i afsnit 2.6)
  • En query kan indeholde bitemporale filtre, der filtrerer data på baggrund af bitemporale felter.
  • Eksemplet ovenfor indeholder bitemporalt point-in-time-filter (virkningstid: "2024-11-12T14:41:33Z") på virkningstidspunktet og (registreringstid: "2025-03-23T14:41:33Z ") på registreringstidspunktet.
• Minimumsfiltrering (beskrevet i afsnit 2.6.2)
  • På bitemporale entiteter skal en query indeholde mindst et bitemporalt point-in-time-filter eller et standardfilter på feltet id_lokalid.
  • Eksemplet ovenfor indeholder to bitemporale point-in-time-filtre, og opfylder derfor minimumsfiltrering.
• Paging (beskrevet i afsnit 2.7)
  • En query skal definere hvilke felter fra entiteten der forespørges og hvordan resultaterne paging.
  • Eksemplet ovenfor returnerer de første 10 resultater (first: 10) for felterne (angivet i ”nodes”) id_lokalid, kommunekode, virkningsaktoer, forretningsproces samt paging-informationer (angivet i ”pageInfo”) for resultatsættet.
• Schema (beskrevet i afsnit 2.8)
  • Hvorvidt en query er gyldig vurderes iht. GraphQL-skemaet, der definerer hvordan data er struktureret, hvilke typer af data der kan hentes, mulige filtreringsoperationer mm.

Om entitetsbaserede GraphQL-tjenester

GraphQL-tjenester tilbydes som entitetsbaserede GraphQL-tjenester. Entiteterne baserer sig på datamodeller fra Grunddatamodellen. En entitet kan f.eks. være en "Adresse" fra DAR, en "Bygning" fra BBR eller et "Jordstykke" fra MAT.

Det at GraphQL-tjenesterne er entitetsbaserede betyder at et kald til en af tjenesterne returnerer data for en enkelt type af entitet. De entitetsbaserede GraphQL-tjenester leverer udelukkende tabulære data og ikke rasterdata (billeddata). Tabulære data forstås som strukturerede data der kan opbevares i tabeller, som f.eks. adresser, men ikke billeddata som f.eks. skærmkort.

Brug af API’et til entitetsbaserede GraphQL-tjenester beskrives nærmere i afsnittet 2.11.

Nedenstående figur giver et overblik over konceptet for entitetsbaserede GraphQL-tjenester. Figuren illustrerer 3 fiktive registre:

• Register A, som har 5 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret og har også en enkelt reference til en entitet i register C udenfor registeret.
• Register B, som har 6 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret og har også en enkelt reference til en entitet i register A udenfor registeret.
• Register C, som har 6 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret.

Figuren illustrerer at entitetsbaserede GraphQL-tjenester ikke udstiller relationer mellem entiteter, samt at tjenesterne ikke kan sammenstille entiteter. Den understøttede funktionalitet (se afsnit 2.1 for et overblik) uddybes i de følgende afsnit.

GraphQL-endepunkter

GraphQL-tjenesterne udstilles gennem URL'er, der følger nedenstående form:

https://graphql.datafordeler.dk/<register>/<version>

<register> er forkortelsen for det register anvenderen forsøger at hente og <version> er versionen for det pågældende register. Versionering er yderligere beskrevet i afsnit 2.9. 

Alle registre, hvis entiteter udstilles via GraphQL-tjenesterne, er vist nedenfor.

Adgangsbegrænsede registre

Nogle registre indeholder data, f.eks. personoplysninger, som kræver godkendelse for at kunne tilgås. Disse data kaldes på Datafordeleren for adgangsbegrænsede data.

Adgang til adgangsbegrænsede data tildeles af registrene ved at en anvender opretter et IT-system og laver en ansøgning gennem selvbetjeningen til det specifikke register på vegne af det nyoprettede IT-system, hvorefter det pågældende register først skal godkende ansøgningen før data kan tilgås. Læs mere om Brugeradgang på datafordeler.dk og hvordan et IT-system oprettes på IT-systemer.

Tabellen nedenfor viser hvilke registre der indeholder adgangsbegrænsede data:

Specialudviklet GraphQL-tjeneste for CVR

Entiteten CVRPerson fra CVR har et enkelt felt som indeholder adgangsbegrænsede data, mens resten af felterne ikke er adgangsbegrænsede. Datafordeleren udstiller derfor den specialudviklede entitet CVRPersonBegraenset gennem en GraphQL-tjeneste, der giver anvendere mulighed for at hente en ikke-adgangsbegrænset udgave af entiteten CVRPerson. Entiteten CVRPersonBegraenset er identisk med CVRPerson bortset fra at feltet CPRPerson er fjernet.

Filtreringsmulighederne på CVRPersonBegraenset-entiteten er de samme som tillades på CVRPerson-entiteten, bortset fra at det ikke er muligt at filtrere på CPRPerson-feltet. GraphQL-skemaet ligner det for CVRPerson-entiteten, dog uden CVRPerson-feltet.

Tjenesten er tilgængelig på følgende URL:

https://graphql.datafordeler.dk/CVR/custom/<version>

Standardfiltrering

GraphQL-tjenesterne understøtter almindelige sammenligningsoperatorer og filtreringsmuligheder (f.eks. <, >, =, in). Nedenstående tabel viser eksempler på datatyper og understøttede operatorer. Det skal bemærkes, at det fremgår i GraphQL-skemaerne for de enkelte registre, hvilke filtreringsmuligheder der er for hver entitet og dennes felter. Tabellen kan ikke anvendes som reference når der skal sammensættes queries til det enkelte register, da det afhænger af den specifikke entitet og dennes felter præcis hvilke operatorer der er understøttet. Læs mere om GraphQL-skemaer i afsnit 2.8. Det er muligt at bruge flere filtre i den samme query, selvom der er nogle begrænsninger for, hvordan filtrering er tilladt.

Geometrisk filtrering

GraphQL-tjenesterne understøtter også geospatiale data og anvendere kan derfor benytte filtre i form af WKT-strenge (Well Known Text) som gives som input til de geometriske filtre. Disse WKT'er repræsenterer geospatiale data, enten i form af en koordinattype, en geometri-type eller lignende datatyper.

De mest almindelige typer af geometriske former er punkter, linjer og polygoner. Et punkt repræsenteres af et koordinatsæt med to eller tre værdier, afhængigt af om det er et punkt i to eller tre dimensioner. En linje repræsenteres af koordinatparrene eller koordinattripletterne for de punkter, der udgør linjen, og en polygon repræsenteres af koordinatpar eller koordinattripletter, der udgør hjørnerne af polygonen. Et eksempel på WKT-formatet for hver af de tre geometrityper i 2D, er vist i nedenstående figur.

Datafordeleren understøtter en række forskellige operatorer. Alle operatorerne fremgår sammen med et link til deres PostGIS-dokumentation i tabellen nedenfor, og hver af funktionerne tager to geometriske former og returnerer en Boolean værdi. Kombinationer af forskellige filtre understøttes også ved hjælp af AND/OR-operatorer.

Et eksempel på hvordan operatoren contains bruges kan ses i nedenstående figur.

De geometriske filtre er implementeret således, at hvis man læser informationen i PostGIS-dokumentation link i Tabel 5, er geometri A altid værdien af registerdatafeltet, og geometri B altid inputgeometrien. Det vil sige, at rækkefølgen er operator(<registerdatafelt>, <input>). Hvis man ønsker den modsatte rækkefølge, bør man i stedet bruge en anden geometrisk operator, der repræsenterer den omvendte operator. En oversigt over disse kan ses i Tabel 6.

Syntaksen for at bruge geometriske filtre, og hvilke felter der kan filtreres geometrisk, er specificeret af GraphQL-skemaet for den pågældende tjeneste, som man ønsker at bruge.

Da geospatiale data kan have forskellige formater afhængigt af, hvilket register det drejer sig om, udfører Datafordeleren udelukkende validering på om det angivne koordinatsystem (CRS) er det samme koordinatsystem som registrets data og at den angivne WKT er valid og repræsenterer en topologisk valid geometri som specificeret i OGC SFS-specifikationen.

Bitemporal filtrering 

På entiteter med bitemporale felter (forklares nærmere på Bitemporalitet | Datafordeler) er følgende to typer queries ofte anvendt:

• Interval-queries, hvor man ønsker data, der er bitemporalt gyldige i en bestemt tidsperiode.
• Point-in-time-queries, hvor man ønsker bitemporalt gyldige data pr. deres angivne tidspunkt.

Ved interval-queries har man mulighed for at specificere standardfiltre, jf. afsnit 2.4, på de bitemporale felter. Ved point-in-time-queries understøttes valgfrie argumenter for registreringstid og virkningstid, som kan angives, når man sender queries. Når disse argumenter ikke gives, returneres fuldt bitemporale data. Bemærk, at for at få data som er gyldigt på et givent tidspunkt, skal man sætte både virkningstid og registreringstid til forespørgselstidspunktet for at få data, der er gyldige på det pågældende tidspunkt.

GraphQL-tjenesterne understøtter muligheden for at kombinere point-in-time-filtrering med enhver anden filtrering, der er tilladt, så man kan hente data, der overholder det angivne tidspunkt samt eventuelle intervalfiltre, geo-filtre eller lignende, de har angivet. Det vil sige, når point-in-time-filteret kombineres med andre filtre, vil forespørgslen ende med at være "point-in-time-filter OG (andre filtre)". Det er ikke muligt at sige point-in-time-filtreret 'ELLER' noget andet filter.

Bitemporal filtrering for CVR

Alle registre der understøtter bitemporal filtrering, understøtter filtrering på både virkningstidspunkt og registreringstidspunkt bortset fra CVR. CVR er det eneste register, hvor anvendere ikke kan specificere et registreringspunkt i deres query. For CVR sættes registreringstidspunktet derimod altid til tidspunktet for forespørgslen, dvs. “registreringstid = NOW()”. Det er muligt at filtrere på virkningstidspunktet på sædvanlig vis.

Minimumsfiltrering

På entiteter med bitemporale felter kræves minimum ét af følgende filtre:

Paging

GraphQL-tjenesterne kræver paging af resultater. At resultaterne pagineres vil sige at resultaterne inddeles i ”sider” og returneres én ad gangen. Anvendere vil således få én side returneret ad gangen og kan efterfølgende lave et nyt kald for at få næste side for på den måde at gennemgå hele datasættet.

Paging er cursor-baseret, hvilket vil sige at der returneres en reference, en såkaldt cursor, til første og sidste resultat (for edges ved hvert enkelt resultat) i det returnerede datasæt ved hvert kald. Denne cursor kan derefter bruges til at hente flere sider ved at anmode om mere data fra cursorens værdi. I praksis kan anvendere bruge cursor-værdien i en efterfølgende query, til at hente den næste side af data, startende fra den position, der er angivet ved den pågældende cursor. Paging er implementeret således at flere identiske anmodninger ved hjælp af den samme cursor vil returnere de samme data, forudsat at registrene ikke opdaterer de underliggende data i mellemtiden.

Paging er udelukkende implementeret som fremadgående paging. Det vil sige, at anvenderne kan hente den næste side af resultater fra en given cursor. Bagudgående paging understøttes ikke.

Paging i queries: PageInfo, nodes og edges

Paging består af tre datastrukturer: PageInfo samt nodes eller edges.

PageInfo indeholder metadata om den nuværende paging og består af følgende felter:

• hasNextPage: Dette felt angiver, om der er endnu en side med resultater.
• hasPreviousPage: Dette felt angiver, om der eksisterer en forrige side med resultater. Da vi ikke understøtter bagudgående paging, er dette altid sat til false.
• startCursor: Dette felt er en cursor, der peger på det første datapunkt i resultatdatasættet.
• endCursor: Dette er en cursor, der peger på det sidste datapunkt i resultatsættet. Denne cursor kan bruges af anvenderen til at hente den næste side af data.

Mens metadata kan hentes via PageInfo, kan data hentes enten som en liste af nodes eller en liste af edges. Nodes og edges adskiller sig på følgende måde:

• I resultatsættet er nodes en liste af datapunkter.
• I resultatsættet er edges en liste af datapunkter med et ekstra metadatafelt cursor, der matcher hvert datapunkt.

Det anbefales, at anvendere benytter nodes til simpel paging, da PageInfo-metadataene er tilstrækkelige. Hvis anvendere har brug for at paging fra en hvilken som helst position på den aktuelle side og ikke fra slutningen af den aktuelle side, skal edges benyttes.

Det er tilladt for anvendere at specificere i GraphQL-queries, at de ønsker både nodes og edges returneret. Dette frarådes, da resultatsættet vil indeholde de samme data to gange.

Inputargumenter for paging

Paging har to inputargumenter, der kan specificeres i en query:

• first: Dette argument angiver hvor mange resultater der ønskes returneret. Dette er sidestørrelsen og skal være et ikke-negativt tal. Hvis dette argument udelades fra en query, returneres standardantallet (100) af resultater. Den maksimalt tilladte sidestørrelse er 1000, og hvis værdien af first er større end den maksimalt tilladte sidestørrelse returneres en fejlmeddelelse.
• after: Dette argument angiver cursoren til det første datapunkt i det resulterende datasæt. Hvis dette argument udelades fra query’en, returneres den første side.

Hvis anvenderen angiver ugyldige værdier for nogen af disse argumenter, vil tjenesterne returnere en fejlmeddelelse, der informerer om, at der er angivet ugyldige paging-argumenter.

Eksempler på paging-query

Følgende query kan bruges til at hente de første 5 datapunkter (første side) af BBR_Bygning-entiteten:

Tjenesten returnerer følgende resultat:

Fra hasNextPage i resultatet ovenfor kan man se at der er flere sider, da den er sat til true. For at hente den næste side kan anvenderen derfor bruge endCursor som after-værdi i den efterfølgende query:

Ved iterativt at gentage dette mønster kan alt den ønskede data hentes.

GraphQL-skemaer

For alle de registre der er udstillet gennem Datafordelerens GraphQL-tjenester, kan anvendere hente GraphQL-skemaer, der beskriver hvordan data er struktureret. Skemaerne specificerer de typer data, der kan hentes, relationerne mellem disse typer og de filtreringsoperationer, der kan understøttes for de pågældende felter. Anvendere kan benytte skemaerne til at se hvilke queries de kan sende, og hvilke data de kan hente.

Skemaerne genereres på baggrund af registrenes datamodeller og er beriget med metadata for hvert register. Denne metadataudtrækningsproces involverer at tage relevant information fra datamodellerne og inkorporere den i skemaerne. Denne ekstra metadata giver anvendere mere omfattende indsigt i de tilgængelige data. Skemaerne findes separat for hvert register og kan hentes ved at tilgå nedenstående url:

https://graphql.datafordeler.dk/<register>/<version>/schema

<register> er forkortelsen for det register anvenderen forsøger at hente og <version> er versionen for det pågældende register. Læs mere om forkortelser i afsnit 2.3 og versionering i afsnit 2.9. Skemaet for version 1 af Skatteforvaltningens Virksomhedsregister (SVR) hentes for eksempel på følgende url:

https://graphql.datafordeler.dk/SVR/v1/schema

Versionering

I GraphQL-tjenesterne versioneres hvert register separat, og alle entiteter, der tilhører det samme register, versioneres under det samme versionsnummer som registret. Det vil sige, at DAR og BBR kan eksistere separat som DAR/v2 og BBR/v5. Men hvis BBR har en change til Bygning-entiteten i deres datamodel, vil alle entiteter i BBR blive opgraderet til BBR/v6, og BBR/v5 vil derefter efter en overgangsperiode blive udfaset.

Cost-beregning

Som en sikkerhedsforanstaltning og af performance-hensyn tilskrives hver query en cost. En cost er en beregnet talværdi der indfanger hvor kompleks og omkostningstung en given query er for Datafordeleren at processere. Cost udregnes inden en query processeres. 

Udregningen af cost er blandt andet baseret på følgende specifikationer:

• Sidestørrelse: Størrelse på paging-siderne der returneres. Jo større sider, jo mere data returneres, hvilket giver en højere cost.
• Filtre: Antallet og type af filtre der benyttes i en query påvirker cost. Jo flere filtre, jo højere cost. Derudover er geometri-filtre mere omkostningstunge og resulterer derfor i en højere cost. Se evt. afsnit 2.4, 2.5 og 2.6 for en oversigt over de forskellige typer af filtre.
• Entiteter: Almindelige og store entiteter har forskellige omkostninger associeret med dem. Store entiteter er mere omkostningstunge end mindre entiteter.
• Felter: Forskellige typer felter har forskellige omkostninger. Geometrier og sammensatte felter er dyrere end simple felter. (Et sammensat felt er et felt der indeholder andre felter.)

Sådan anvender du entitetsbaserede GraphQL-tjenester

GraphQL-tjenesterne på Datafordeleren tilgås via et GraphQL-API. Dette afsnit beskriver, hvordan det vil være muligt at danne et overblik over hvilke entiteter man kan tilgå, samt hvordan data hentes. GraphQL-tjenesterne kan tilgås på registerbasis og kræver at du benytter en af de tre autentifikationsmetoder beskrevet i afsnit 3. 

Ovenstående figur viser hvordan GraphQL-API'et overordnet set anvendes. Her hentes GraphQL-skemaet først for det pågældende register ved at tilgå https://graphql.datafordeler.dk/<register>/<version>/schema, hvorefter det ønskede data hentes, ved at sende en query til https://graphql.datafordeler.dk/<register>/<version>.

Hent Schema

Parametre

Returværdier

Denne tjeneste returnerer altid en fil ved HTTP 200 – OK. Filen indeholder et GraphQL-schema med metadata om GraphQL-tjenesten, der beskriver hvilke entiteter der findes for det pågældende register og hvordan data fra disse hentes.

Eksempler på brug af tjenesten

Hent skema for DAGI med versionsnummer v1 ved brug API-nøgle:

• https://graphql.datafordeler.dk/DAGI/v1/schema?apiKey=placeholderNoegle

Send query

Parametre

Returværdier

Denne tjeneste returnerer et json-response ved HTTP 200 – OK.

Eksempler på brug af tjenesten

Hent de første 100 datapunkter fra entiteten DAR_Adresse fra version 1 af DAR inden for den angivet periode ved at sende nedenstående query ved brug af API-nøgle:

• https://graphql.datafordeler.dk/DAR/v1?apiKey=placeholderNoegle

Hent data der var gældende den 12/11/2024, kl. 14:41:33 med kommunekode “0550” fra entiteten BBR_Bygning fra version 1 af BBR ved at sende nedenstående query som et POST-request  ved brug af API-nøgle:

• https://graphql.datafordeler.dk/BBR/v1/?apiKey=placeholderNoegle