Dataforsyningen-token: opret, navngiv, forny — og hvad du gør, når den udløber

Hvad du får — og hvad du ikke får

Du opretter en gratis konto på dataforsyningen.dk og laver derefter tokenen selv i selvbetjeningen. Der er ingen ansøgning, ingen godkendelse og ingen regning. Adgangen til de nationale ortofotos er fri.

Til gengæld er det ikke OAuth. Der er ingen refresh, ingen scopes og ingen klienthemmelighed. En token er en streng, som du selv opretter, selv navngiver, selv giver en udløbsdato og selv udskifter. Hele livscyklussen ligger hos dig — og det er netop derfor, den skal besluttes én gang i stedet for at blive opfundet forfra hver gang en token holder op med at virke.

Den enkeltdetalje, der afgør, om det bliver let eller svært: du kan have flere tokens på den samme konto, og hver af dem kan have sit eget navn og sin egen udløbsdato.

To steder tokenen kan stå — og kun ét sted den bør stå

Tjenesten tager imod tokenen to steder: som HTTP-headeren token, hvilket er den anbefalede måde, eller som URL-parameteren &token=.

Forskellen er ikke teknisk. Den er driftsmæssig. En token i URL'en ender i adgangslogs, i browserhistorik, i bogmærker, i fejlrapporter og i den referer, din egen side sender videre til tredjepart. En token i headeren ender ingen af de steder. URL-parameteren findes, fordi den er den eneste mulighed i et kortbibliotek, der kun kan få en URL at hente fliser fra — og det er den eneste gode grund til at bruge den.

Uanset hvilken af de to du vælger: kaldet skal være HTTPS, og der kræves TLS 1.2 eller nyere. Almindelig HTTP bliver afvist, ikke omdirigeret. Et bibliotek, der plejer at ordne opgraderingen for dig, gør det ikke her — du får en forbindelse, der lukkes, og ingen fejlmeddelelse, der forklarer hvorfor.

# Anbefalet: tokenen står i headeren og havner aldrig i en log
curl -H "token: DIN_TOKEN" \
  "https://api.dataforsyningen.dk/orto_foraar?service=WMS&request=GetCapabilities&version=1.3.0"

# Virker også — men brug den kun dér, hvor du kun kan aflevere en URL
curl "https://api.dataforsyningen.dk/orto_foraar?service=WMS&request=GetCapabilities&version=1.3.0&token=DIN_TOKEN"

Det samme gælder REST-tjenesterne, som ligger på https://api.dataforsyningen.dk/rest/ efterfulgt af servicenavnet. Samme konto, samme token, samme header.

Lav flere, og navngiv dem efter det system, de sidder i

Én token til det hele er den beslutning, der gør alle senere beslutninger dyre. Den dag den skal udskiftes — fordi den udløber, fordi en udvikler stopper, eller fordi den har ligget i et repository i tre uger — skal den skiftes alle steder på én gang, og du ved ikke længere, hvor alle stederne er.

Flere tokens med navne vender det om. Du kan slette én uden at holde vejret, fordi navnet allerede fortæller dig, hvad der går i stå.

Udløbsdatoen er en funktion, ikke en irritation

Du kan sætte en udløbsdato på hver token. Fristelsen er at lade være — eller at sætte den så langt ude i fremtiden, at den aldrig bliver nogens problem. Begge dele flytter bare problemet hen et sted, hvor ingen kigger.

En token uden udløb lever, til den bliver lækket. En token med en kendt dato er en opgave i en kalender. Sæt datoen, skriv den ned sammen med navnet, og gør udskiftningen til noget, der sker på en formiddag, du selv har valgt.

Rutinen, der holder: opret den nye token, før den gamle udløber. Rul den ud. Kontrollér at trafikken rent faktisk kører på den nye. Først derefter sletter du den gamle. Rækkefølgen er hele pointen — gør du det omvendt, arbejder du med et nedbrud kørende.

Dagen den udløber

Hvordan ved jeg, at det er tokenen?

Symptomet er karakteristisk: alt fra ét system holder op med at virke på én gang, mens dine andre systemer kører videre. Ingen gradvis forværring, ingen enkelte fejlende kald. Den form peger på en legitimation, ikke på en tjeneste, der har det skidt.

Gæt ikke på statuskoden — få den at se. Kald capabilities med curl -i fra den samme maskine og med den samme token, og læs den første linje i svaret. Det tager ti sekunder og fjerner halvdelen af de mulige årsager.

Er det tokenen, eller er det mit kald?

Kør den samme URL igennem med en frisk token. Virker den, var det tokenen. Virker den ikke, er det kaldet — og så er det næsten altid koordinatsystem, akserækkefølge eller enheden i din bbox. De tre har deres egne artikler, som er linket nederst.

Kan jeg ikke bare lave en ny og lade den gamle stå?

Du kan, og det er netop derfor du ikke skal. En ubrugt token, som ingen længere kan huske hvad hed, er den token, der stadig ligger i et gammelt repository. Når udskiftningen er kontrolleret, slettes den gamle i samme arbejdsgang. Ellers bliver listen over tokens i løbet af et år til en liste, ingen tør røre ved.

Er der en grænse for, hvor meget jeg må kalde?

Der er ikke offentliggjort en fair use-grænse eller en kvote for Dataforsyningens webtjenester. Det er ikke det samme som, at der ingen er. Risikoen er ikke juridisk, men driftsmæssig: en proxy, der hamrer løs på deres endpoints, er præcis den slags, der får en token spærret.

Cache dine fliser, og cache dem længe. Det er både hurtigere for dig og venligere ved en tjeneste, der er gratis og ikke giver nogen driftsgaranti.

Når vedligeholdelsen ikke er din opgave

Alt ovenstående er arbejde, der gøres én gang og derefter holdes ved lige: konto, token, navngivning, udløbsdatoer, en udskiftningsrutine, lagnavne der skifter mellem årgange, og en cache, der er venlig nok ved en gratis tjeneste uden driftsgaranti.

Det er præcis det stykke, vores API fjerner. Én nøgle hos os i stedet for en token hos Dataforsyningen, ét kald, og kildeangivelsen leveret med i svaret, så CC BY 4.0 er overholdt uden at du skal huske det.

Skal du derimod bruge ét ortofoto over én adresse én gang, så brug fremgangsmåden ovenfor. Den er gratis, og den er bygget til netop det.

Kilder og videre læsning

• Dataforsyningen — log ind og token Konto, selvbetjent token, flere tokens med navn og udløbsdato, header kontra URL-parameter, og kravet om HTTPS.
• Dataforsyningen — kom i gang med webservices Servicetyperne og hvordan den enkelte tjeneste adresseres.
• Sådan henter du et dansk ortofoto over WMS i EPSG:25832 Selve GetMap-kaldet, servicenavnene, og de tre fejl der ligner en serverfejl men er dine egne.
• EPSG:25832 eller EPSG:4326? Hvilket koordinatsystem du skal gemme i, og akserækkefølgen der vender om mellem WMS-versionerne.