Dette dokument er en guide til hvordan anvendere kan bruge Datafordelerens entitetsbaserede GraphQL-tjenester.
Dokumentet er opdelt i tre dele:
- Første del af dokumentet beskriver hvad entitetsbaserede GraphQL-tjenester er og hvordan de bruges.
- Anden del af dokumentet beskriver hvordan autentifikation og autorisation håndteres.
- Tredje del af dokumentet forklarer forskelle mellem GraphQL og de nuværende REST-tjenester på Datafordeleren, samt hvordan anvendere kan komme i gang med at anvende GraphQL-tjenester.
Dokumentet er tiltænkt følgende læsere: - Eksisterende anvendere af Datafordeleren der bruger den Nuværende Datafordelers REST-tjenester, som ønsker at komme i gang med at bruge de entitetsbasereede GraphQL-tjenester i stedet.
- Nye anvendere, der vil i gang med at bruge GraphQL-tjenesterne på Datafordeleren.
Begreber
I dette dokument bruges begreberne i Tabel 1. Bemærk at begreberne også er yderligere forklaret i løbet af dokumentet med eksempler.
...
Begreb
...
Beskrivelse
...
Nuværende Datafordeler
...
REST-tjenester:
...
...
...
...
GraphQL er en funktionalitet på Datafordeleren til udstilling af data. Dette dokument beskriver hvordan anvendere kan benytte GraphQL-tjenesterne til at hente tabulære data fra registrene på Datafordeleren.
...
...
...
...
...
...
...
...
...
...
...
...
- Entitet (beskrevet i afsnit 2.2): Hver query skal specificere hvilken entitet den omhandler. Eksemplet ovenfor viser en query for entiteten BBR_Bygning fra BBR og specifikt kun for 3 kolonner (angivet i "nodes"): id_lokalId, kommunekode og virkningsaktoer.
- Endepunkt (beskrevet i afsnit 2.3): En query sendes til et GraphQL-endepunkt som et GET- eller POST-request.
- Standardfiltre (beskrevet i afsnit 2.4): En query kan indeholde standardfiltre der filtrerer data. Query'en ovenfor indeholder to standardfiltre: et lighedsfilter (eq: "0550") på kommunekode-kolonnen og et tekstfilter (startsWith: "Konvertering") på virkningsaktoer-kolonnen.
- Geometriske filtre (beskrevet i afsnit 2.5): En query kan også indeholde geometriske filtre, der filtrerer data på baggrund af geometri-felter.
- Bitemporale filtre (beskrevet i afsnit 2.6): En query kan også indeholde bitemporale filtre. Query'en oven for indeholder et bitemporalt point-in-time-filter (virkningstid: "2024-11-12T14:41:33Z") på virkningstidspunktet.
- Paging (beskrevet i afsnit Fejl! Henvisningskilde ikke fundet.): En query kan også definere hvordan data pagineres. Query'en oven for returnerer de første 10 rækker (first: 10) givet filtreringen samt paginginformation for resultatsættet (angivet i "pageInfo").
Om entitetsbaserede GraphQL-tjenester
GraphQL-tjenester tilbydes som entitetsbaserede GraphQL-tjenester og baserer sig på de datamodeller som registrene har på Datafordeleren.
En entitet svarer til en tabel defineret i registrenes datamodel fra Grunddatamodellen: https://datafordeler.dk/grunddatamodel/
En entitet kan eksempelvis 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 fx adresser men ikke billedtyper som skærmkort.
Brug af API'et beskrives nærmere i afsnittet 2.11. 
Figur 2: Opsummering af GraphQL-funktionalitet
En opsummering hvad GraphQL-tjenesterne består af, kan ses i ovenstående figur. Figuren viser 3 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.
I modsætning til registrenes datamodeller har de entitetsbaserede GraphQL-tjenester på nuværende tidspunkt ingen relationer men kaldes enkeltvis per entitet.
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 i Tabel 2 nedenfor.
...
Register
...
Forkortelse
...
Bygnings- og Boligregistret
...
BBR
...
Danmarks Administrative Geografiske Inddeling
...
DAGI
...
Danmarks Adresseregister
...
DAR
...
...
Adgangsbegrænsede registre
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Datatyper
...
...
...
...
...
...
...
...
Boolean
...
...
...
Tabel 4: Understøttede datatyper og operatorer
Geometrisk filtrering
...
Datatyper
...
Understøttede operatorer
...
PostGis Link
...
Geometri
...
contains(koordinatsystem, geometri)
...
https://postgis.net/docs/ST_Contains.html
Point POINT (3 5) Line LINESTRING (6 4, 8 2, 7 1) Polygon POLYGON (1 1, 3 3, 4 2, 4 0, 1 1) |
...
covers(koordinatsystem, geometri)
...
https://postgis.net/docs/ST_Covers.html
...
coveredBy(koordinatsystem, geometri)
...
https://postgis.net/docs/ST_CoveredBy.html
...
...
...
...
...
...
...
...
...
...
...
...
...
Geometrisk operator | Omvendte operator |
contains | within |
covers | coveredBy |
coveredBy | covers |
crosses | Ingen. crosses er symmetrisk |
intersects | Ingen. intersects er symmetrisk |
within | contains |
overlaps | Ingen. overlaps er symmetrisk |
touches | Ingen. touches er symmetrisk |
Tabel 6: Geometriske operatorer og deres omvendte operatorer.
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. Når man angiver WKT-strengen for den geometri, der skal filtreres på, skal man også angive, hvilket koordinatsystem (CRS) deres WKT tilhører, som illustreret i eksemplet i Figur 4.
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
Der er to typer queries, som man kan udføre på bitemporale data:
- 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.
...
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.
Paging
GraphQL-tjenesterne understøtter 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.
Pagingen 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 pagination, 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: Cursoren, der matcher hver datapunkt.
Det anbefales, at anvendere benytter nodes til standard paginganmodninger, da PageInfo-metadataene er tilstrækkelige. Hvis anvenderne har brug for at paginere 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 deres 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 anvenderen ønsker returneret. Dette er sidestørrelsen og skal være et ikke-negativt tal. Hvis dette argument udelades fra query'en, returneres standardantallet af resultater.
- 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.
...
...
...
...
Eksempler på paging-queries
...
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 hver 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 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. Costen udregnes inden en query processeres, hvorefter den pågældende query enten sendes videre i systemet eller bliver afvist hvorved anvenderen vil modtage en fejlmeddelselse der informerer om at query'en var for kompleks.
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 også costen. Jo flere filtre, jo højere cost. Derudover er geometri-filtre mere omkostningstunge og resulterer defor 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 Et sammensat felt er et felt der indeholder andre felter. felter er dyrere end almindelige felter.
Som anvender skal man ikke tage stilling til hvor omkostningstung en query er så længe den ikke overstiger den maksimale cost, i hvilket tilfælde den pågældende query vil blive afvist med en fejlbesked.
Sådan anvender du entitetsbaserede GraphQL-tjenester
...
Hent Schema
...
Hent Schema
...
URL
...
https://graphql.datafordeler.dk/<register>/<version>/schema
...
HTTP-metode
...
GET
...
Headere i forespørgsel
...
Content-Type: application/json
...
Returværdier
...
- Returnerer HTTP 200 – OK, ved succes.
- Returnerer HTTP 400 – Bad Request, ved angivelse af forkerte parametre.
- Returnerer HTTP 404 – Not Found, hvis den angivne ressource ikke kan findes.
- Returnerer HTTP 500 – Internal Server Error, hvis der er sket en ukendt fejl
...
Adgang
...
Tjenestebruger med brugernavn og password, IT-system med API-nøgle, OAuth Shared Secret eller OAuth Certifikat.
Parametre
Navn | Type | Beskrivelse | Obligatorisk? |
Register | String | Angiver hvilket register det pågældende skema skal hentes for.
| Ja |
Version | String | Angiver hvilken version af datamodellen det pågældende register skal være. | Ja |
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 v2 ved brug API-nøgle:
Send query
...
Send query
...
URL
...
| Wiki Markup |
|---|
*"nodes": \[* |
...
1) Åben Postman og klik på ”Collections” i venstre side. Collections er en folder/mappe med et bestemt navn, hvor du kan samle alle dine queries til Datafordeleren og eventuelt navngive dem efter behov.
For at oprette en collection trykker du på ”+” ikonet og vælger ”Blank collection”. Derefter kan du i toppen navngive din collection.
2) Når en collection er oprettet, kan du oprette en request ved at højreklikke på sin collection eller trykke på de 3 prikker og derefter vælge ”Add request”.
Her kan du også navngive din request efter behov.
...
HTTP-metode
...
GET & POST
...
Headere i forespørgsel
For POST-requests:
BBR/v1 for at kunne lave queries til BBR-version 1.
4) Vælg requesten i venstre side (hvis den ikke allerede er aktiv som i det forrige trin) og klik på ”Authorization” for at skifte til en anden fane. Her skal du vælge ”OAuth 2.0” i ”Auth Type” menuen.
Postman skulle gerne skifte indholdet når du har valgt en ny auth type.
5) Du skal herefter scrolle ned i den aktive ”Authorization” fane indtil du kan se en ”Configure New Token” overskriften.
Under overskriften vil der være en række felter som skal udfyldes som beskrevet herunder.
- I ”Token Name” kan du give din Access Token et passende navn.
- I ”Grant type” menuen skal du vælge ”Client Credentials”. Her vil Postman ændre felterne under med dem som relevant for din konfiguration af OAuth.
- I ”Access Token URL” skal du indsætte følgende link - https://auth.datafordeler.dk/realms/distribution/protocol/openid-connect/token
- I ”Client ID” skal du indsætte det Client ID som de har modtaget efter at have oprettet det i OAuth sektionen på Datafordeler Administration.
- I ”Client Secret” skal du indsætte den Shared Secret som du har modtaget efter at have oprettet det i OAuth sektionen på Datafordeler Administration.
- Anvenderen kan ignorere ”Scope” feltet, men skal verificere at ”Client Authentication” feltet er sat til ”Send as Basic Auth header”.
6) Efter du har udfyldt de nødvendige felter, kan du hente dit Access Token ved at rulle ned indtil du ser en orange knap der hedder ”Get New Access Token” og klikke på den.
Derefter vil Postman åbne et vindue som indikerer at applikationen er gået i gang med at hente Access Token fra Datafordeleren.
Når Access Token er hentet, vil Postman opdatere vinduet med et grønt flueben og med teksten ”Authentication complete”. Herefter kan du vente 5 sekunder eller trykke på ”Proceed” knappen i nederste højre hjørne. Herefter vil Postman åbne et nyt vindue.
7) Når Postman har åbnet det næste vindue, vil Access token og dets navn stå under ”Token Details”.
Du kan nu trykke på ”Use Token” til at bruge den til at lave queries i Postman eller kopierer access token til anden applikation.
8) Hvis du trykker på ”Use Token” vil Postman automatisk udfylde det i den request som du oprettede tidligere. Herefter kan du lukke vinduet og klikke på ”Body” fanen, efterfuldt ved at klikke på GraphQL muligheden længst til højre. Til sidst kan du skrive en GraphQL-query til BBR og indsætte det i ”Query” tekstfeltet.
9) Når du er klar til at indsende din query kan du trykke på ”Send” oppe i højre hjørne.
Herefter vil svaret fra GraphQL tjenesten blive vist i bunden.
2) Herefter skal OAuth 2.0-indstillinger opsættes for certifikatet. Gå ind under ”Authorization” i requesten, og scroll ned til ”Configure New Token”.
Under overskriften vil der være en række felter som skal udfyldes som beskrevet herunder.
a. I ”Token Name” kan du give din Access Token et passende navn.
b. I ”Grant type” menuen skal du vælge ”Client Credentials”. Her vil Postman ændre felterne under med dem som relevant for din konfiguration af OAuth.
c. I ”Access Token URL” skal du indsætte følgende link - https://auth-oces.datafordeler.dk/realms/distribution/protocol/openid-connect/token.
d. I ”Client ID” skal anvenderen indsætte det Client ID som de har modtaget efter at have oprettet det i OAuth sektionen på Datafordeler Administration.
e. Du kan ignorere ”Scope” feltet, men skal verificere at ”Client Authentication” feltet er sat til ”Send client credentials in body”.
3) Vælge ”Settings” oppe i højre hjørne:
4) Vælg herefter ”Add Certificate”.
5) Angiv herefter ”host” og certifikatet.
- Host skal være https://auth-oces.datafordeler.dk.
- PFX file skal pege på certifikatet som indeholder den private nøgle. Det er vigtigt at dette certifikat stemmer overens med det certifikat som blev uploadet inde i portalen.
- Passphrase skal stemme overens med password til certifikatet.
- Bemærk at det kan være nødvendigt at installere ”Den Danske Stat” rodcertifikatet på anvenders maskine for at maskinen stoler på det certifikat der er vedhæftet inde i Postman.
...
Body
For GET-requests:
...
Returværdier Returværdierne for HTTP-statuskoderne afhænger af hvilken Accept-header der specificeres. Disse værdier er hvis Accept-headeren ikke er angivet som beskrevet i "Headere i forespørgsel".
...
- Returnerer HTTP 200 – OK, ved succes.
- Returnerer HTTP 400 – Bad Request, ved angivelse af forkerte parametre.
- Returnerer HTTP 404 – Not Found, hvis den angivne ressource ikke kan findes.
- Returnerer HTTP 500 – Internal Server Error, hvis der er sket en ukendt fejl
...
Adgang
...
- Ikke-adgangsbegrænset data: IT-system med API-nøgle, OAuth Shared Secret eller OAuth Certifikat.
- Adgangsbegrænset data: IT-system med OAuth Shared Secret eller OAuth Certifikat og på en defineret IP-Allowlist og så skal IT-systemet have eksplicit godkendelse fra det pågældende register. Se afsnit 0 for yderligere information.
Parametre
Navn | Type | Beskrivelse | Obligatorisk? |
Register | String | Angiver hvilket register det pågældende skema skal hentes for.
| Ja |
Version | String | Angiver hvilken version af datamodellen det pågældende register skal være. | Ja |
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 ved at sende nedenstående query ved brug af API-nøgle til endepunktet:
...
...