Opsætning og brug af REST API

Denne vejledning henvender sig til eksterne parter, der ønsker at anvende Plandata.dk's REST-snitflade for system-til-system-indberetning af planer til Plandata.dk.

Det eksterne REST API er gjort tilgængeligt i produktionsmiljøet i januar 2024, og det er udviklet til at erstatte den ældre SOAP-service, som planlægges udfaset i løbet af 2024.

I udviklingen af REST-snitfladen har der været særligt fokus på følgende forbedringer ift. den ældre SOAP-snitflade.

• Validering: Alle kald til REST API'et der ændrer på en plan, bliver tjekket op imod det samme sæt af valideringsregler, som anvendes ved indberetning igennem Plandata.dk's web-baserede brugerflade (https://indberet.plandata.dk). Dette sikrer, at succesfuld indberetning af planer igennem REST API'et ikke vil udløse fejl, når de samme planer efterfølgende tilgås i bl.a. web-brugerfladen, og der sikres desuden en højere datakvalitet.
• Autentificering og Rollestyring: Plandata.dk's REST API bruger en moderne JWT-baseret autentificeringsmetode, som sikrer at kommunale plandata-indberettere kun har adgang til at ændre i planer i deres egen kommune. Authentificeringen af en brugers adgang til REST API'et forholder sig desuden til samme MitID-rettigheder, som den web-baserede brugerflade, hvilket betyder, at enhver bruger med adgang til web-brugerfladen vil have en tilsvarende adgang igennem REST API'et og omvendt. Authentificering og udstedelse af JWT token sker via login med MitID. Som en midlertidig løsning i en overgangsperiode, kan dette også ske via login med en Basic Auth-bruger. Denne vejledning har primært fokus på den langsigtede løsning om at bruge MitID, men indeholder også vejledning og information om brug af REST API'et med Basic Auth.

Både ift. at tilgå REST API'et i produktionsmiljøet og i pre-produktionsmiljøet (vores eksternt tilgængelige testmiljø), skal der logges ind med en bruger, som kan autentificeres i Digitaliseringsstyrelsens system for NemLog-in. Med en autentificeret bruger kan der hentes en access token, som giver en tidsbegrænset adgang for at indberetning til Plandata.dk.

PRODUKTION

For at anvende Plandata REST API i produktionsmiljøet, skal man anvende et MitID Erhverv fra den relevante kommune, som har tilknyttet de nødvendige rettigheder. Det er samme rettigheder, som anvendes til indberetning via Plandata.dk's egen web-brugerflade, indberet.plandata.dk.

PRE-PRODUKTION

For at anvende Plandata.dk's REST API i pre-produktionsmiljøet skal der oprettes en testbruger i Digitaliseringsstyrelsens system. Der findes flere muligheder for, hvordan test-MitID'et kan sættes op. Disse muligheder gennemgås i næste afsnit.

Det anbefales, at pre-produktionsmiljøet anvendes til at afprøve tredjepartsløsningers brug af REST API'et, inden der indberettes til produktionsmiljøet. På testmiljøet er der som udgangspunkt ikke den samme kommune-specifikke begrænsning ift. adgang til indberetning af planer.

Administrering af testbrugere i PREPROD

For at bruge Plandata REST API i pre-produktionsmiljøet findes der tre muligheder for at få adgang til en testbruger:

1. Henvend jer til Plandata-supporten mhp. at vi opretter en testbruger til jer, som tilknyttes vores Plandata's egen test-brugerorganisation.
   1. Denne testbruger vil få privilegier tilknyttet et test-CVR, som er whitelistet i vores system. Dette gør at brugeren har adgang til alle kommuner og giver mulighed for at komme hurtigt igang med at teste
   2. Denne mulighed reflekterer ikke til fulde, hvordan brugerorganisation og privileger for indberettere vil se ud i Plandata REST API i produktionsmiljøet, fordi der i produktion ikke vil være adgang til alle kommuner. Hvis opsætning fsva. adgangen til specifikke kommuner skal afspejle produktionsmiljøet, anbefales i stedet opsætning i Mulighed 3.
2. Lav selv jeres egen test-brugerorganisation og derefter testbrugere i Digitaliseringsstyrelsens "devtest4-miljø" for NemLog-in.
   1. En ny brugerorganisation oprettes her: https://testportal.test-devtest4-nemlog-in.dk/BO. Når brugerorganisationen er oprettet, skal I henvende jer til Plandata-supporten mhp. at få whitelistet test-brugerorganisationens CVR-nr, således der åbnes for indberetning til Plandata.dk.
   2. Første led i opsætningen af denne mulighed tager længere tid end Mulighed 1, men derfra får I selv fuld kontrol over, hvilke brugere der tilknyttes jeres test-organisation.
   3. Ligesom for Mulighed 1, så kan Mulighed 2 give adgang til alle kommuner, hvorved den bliver mere fleksibel til testformål, men til gengæld ikke til fulde afspejler opsætningen, som den vil se ud i produktionsmiljøet. Hvis opsætning fsva. adgangen til specifikke kommuner skal afspejle produktionsmiljøet, anbefales i stedet opsætning i Mulighed 3.
3. Anmod om, at NemLog-in-administratoren for en specifik kommune opretter testorganisation og testbrugere til jer i Digitaliseringsstyrelsens "devtest4-miljø". Denne bruger kan derved få privilegier tilknyttet den specifikke kommune. Dette reflekterer opsætningen og proces ift. hvordan det vil fungere i PROD, men placerer til gengæld opgaven for oprettelse og vedligehold af testbrugere hos de enkelte kommuner.

I det følgende beskrives det, hvordan en bruger autentificerer sig mod en Token Service som Plandata udstiller for at hente en access token i forskellige miljøer. For at implemente et programmatisk flow anbefales det at man implementerer sin egen token løsning. Se separate vejledning for mere herom: Bestilling og implementering af token-klient.

Denne access token bruges som autentificering ved kald til Plandata REST API. En access token er gyldig i 1 time, hvorefter fortsat indberetningsarbejde vil kræve fornyelse af token.

PREPROD

1. Tilgå OpenID Connect (OIDC) siden for PREPROD på https://indberetpreprod.plandata.dk/plandata-api/oidcClient/index
2. I toppen, klik "Login/forny session":
   
3. Brugeren bliver redirected til NemLog-in.
4. I toppen, vælg "Test login":
   
5. Udfyld med brugernavn og adgangskode for jeres testbrugere i devtest4 (se afsnit Administrering af testbrugere i PREPROD samt uddybende vejledninger under dette afsnit).
6. Brugeren bliver herefter viderestillet tilbage til OIDC-siden (se længere nede).

PROD

1. Tilgå OpenID Connect (OIDC) siden for PROD på https://indberet.plandata.dk/plandata-api/oidcClient/index
   1. Denne side er pt. kun åben for interne adresser.
2. I toppen, klik "Login/forny session":
   
3. Brugeren bliver viderestillet til MitID, hvor brugeren skal logge ind med sit certifikat.
4. Brugeren bliver herefter viderestillet tilbage til OIDC-siden (se længere nede).

OIDC siden efter autentificering

Hvis alt er gået godt så skal teksten efter status være: "Bruger er logget ind". I toppen vises også JSON data for brugerens profil, inklusive brugerens navn og en liste af privilegier (hvis brugeren har nogle tildelt):

Brugerens access token kan nu hentes ved at klikke på Vis access token:

Login via Basic Auth (midlertidig løsning)

En Basic Auth-bruger kan i særlige tilfælde udstedes som midlertidig løsning, hvis en MitID-baseret opsætning ikke vurderes at understøtte de forretningsmæssige formål tilstrækkeligt under de nuværende forudsætninger. Kontakt Plandata-supporten for at bestille Basic Auth-adgang. Det understreges, at Basic Auth betragtes som en midlertidig løsning, og at det er hensigten, at alle tredjeparter skal overgå til MitID.

Hentning af token

For de tilfælde hvor det ikke er muligt at hente en token via MitID, er der implementeret mulighed at hente en token ved at autentificere sig med Basic Auth.

Dette gøres via et REST kald til Sector9's token-endepunkt med udleveret login information.

HTTP-Request

Brug af token

For at autentificere kald til Plandata REST API, skal 'Authorization' header sættes til 'Bearer <token>', hvor <token> er access token kopieret fra OIDC klienten, f.eks:

REST-snitfladen er dokumenteret ved brug af Swagger, som også giver mulighed for at afprøve hvert endpoint.

Der er separate endpoints for hver plantype for hhv. indberetning, opdatering, statusskifte, hent, valideringstjek m.m. I denne sammenhæng betragtes eksempelvis lokalplaner, delområder og byggefelter i teknisk forstand som forskellige, men relaterede plantyper.

Til forskel fra SOAP-servicen, så er det igennem REST API'et ikke muligt i ét kald at indberette en plan, der på forhånd er beriget med alle oplysninger og data. I stedet oprettes eksempelvis en lokalplan først som en næsten "tom skal" i status "kladde til forslag". Derefter kan den beriges med data. Når kladden er klar og overholder valideringskrav, så kan man igennem et separat kald skifte planens status og fx offentliggøre sit planforslag. Det er muligt at foretage valideringstjek af sin plan, imens den er i kladde-status, så man løbende kan tjekke for mangler og eventuelle fejl, inden planen offentliggøres. Flowet er illusteret i figuren herunder.

Swagger - API Dokumentation

Swagger er et værktøj for automatisk at dokumentere alle endepunkter, deres input/outputs og forventede HTTP statuskoder i Plandata REST API. Nedenstående tabel samler links til vores swagger-sider i forskellige miljøer. Data kan enten vises i en brugervenlig grænseflade (Swagger UI) eller som JSON data.

API standarder

Nedenstående beskriver de standarder, vi overholder for endepunkterne. Dette kan også ses i Swagger.

HTTP Statuskoder

2xx

4xx

5xx

HTTP-metoder

Følgende tabel beskriver hvilke metoder som bruges i Plandata REST API, og hvornår de skal bruges. Dette fremgår også af Swagger-dokumentationen.

Alle endepunkter skal følger nedenstående mønster:

/<ressourcetype>/<action>

• <ressourcetype> skal erstattes med navnet for den ressource man vil tilgå, f.eks. lokalplan, landzonetilladelse eller hoeringspart. 
• <action> skal erstattes med den action man vil udføre, f.eks. hentLokalplan, opretHoeringspart eller sletByggefelt.

Inputformat

Input data skal vare i JSON/GeoJSON-format.

Geometri

Geometri kan angives for en plan via felterne geometri og projection.

Feltet projection specificerer den projection som geometriens koordinater er specifierede i, og skal altid være "EPSG:25832".

Feltet geometri specificerer koordinater og type af geometri i gyldigt GeoJSON-format, mere info her: https://en.wikipedia.org/wiki/GeoJSON. Typen skal altid være "MultiPolygon". Nedenstående er et eksempel på en gyldig GeoJSON-streng:

Datoer

Alle datofelter skal følge ISO 8601 format, dvs. "yyyy-mm-dd". Eksempel:

Outputformat

Output data returneres i JSON/GeoJSON-format. Hvis alt er vellykket returneres hvad der er blev oprettet, opdateret eller slettet af brugerens kald. Hvis noget gik galt, returneres et JSON-response med information om hvad der gik galt. Dataen skal have følgende struktur:

fejlType

Tilgængelige fejltyper:

Hent lokalplan

Eksempel på hent af en lokalplan, der er i forslags-status i Københavns Kommune (kommunekode 101). I eksemplet er det specificeret, at geometri skal ekskluderes mhp. at holde response mere overskueligt. Parameteren maxPageSize er også indstillet til at begrænse antallet af returnerede planer til 10.

Response

Status: 200 OK

Opret lokalplan

Opret en ny Lokalplan i status Kladde til forslag i København (kommunekode 101). Her specificeres også plannummer og plannavn.

Response

Status: 201 CREATED