Komme i gang med API-et

Nedlasting av WSDL-filer

På nettsidene til hvert enkelt matrikkelsystem kan man laste ned WSDL- og XSD-filer for API.

Bygging av klienter fra WSDL

Forskjellige utviklingsmiljøer håndterer generering av klientkode på ulike måter. Nedenfor finner du eksempler på hvordan dette gjøres med Java (JAXB) og .NET.

Eksempel 1: `wsimport` for Java

Hvis du bruker Java som utviklingsverktøy på klientsiden, kan du benytte verktøyet wsimport. Fram til JDK 11 var wsimport inkludert direkte i JDK (Java Development Kit).

En typisk kommando for å generere klientkode basert på en WSDL-fil:

c:\temp\wstest>wsimport c:\temp\wstest\wsdls\AdresseServiceWS.wsdl -d c:\temp\wstest\src -Xnocompile -keep -wsdllocation /wsdls/AdresseServiceWS.wsdl

info

Det er funnet noen rariteter ved kjøring av kommandoene. Hvis man skal ha flere WSDL-er i samme kildekodekatalog, er det viktig at StoreServiceWS eller RapportServiceWS kjøres som de siste wsimport-kommandoene.

Hvis disse ikke kjøres sist, kan det oppstå problemer med package-info.java og kvalifisering av pakkenavn, noe som igjen kan føre til feil under kjøring av applikasjonen.

Eksempel 2: .NET

I .NET-miljøer kan man benytte verktøyet svcutil, som følger med Visual Studio. Det er også mulig å installere verktøyet via Microsoft sine SDK-er, men den genererte koden er i praksis vanskelig å bruke uten Visual Studio og tilhørende biblioteker.

Verktøyet krever at man definerer en mapping fra namespace til pakkenavn (namespace mapping) for alle WSDL-pakker som skal inngå i den genererte klientkoden. Under følger et eksempel på en slik mapping for matrikkelens tjenester.

setlocal
set nsmap_domain=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain
set nsmap_domain_adresse=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/adresse,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.adresse
set nsmap_domain_adresse_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/adresse/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.adresse.koder
set nsmap_domain_aktivitetsliste=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/aktivitetsliste,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.aktivitetsliste
set nsmap_domain_aktivitetsliste_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/aktivitetsliste/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.aktivitetsliste.koder
set nsmap_domain_bruker=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/bruker,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.bruker
set nsmap_domain_bruker_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/bruker/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.bruker.koder
set nsmap_domain_bygning=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/bygning,no.statkart.matrikkel.matrikkelapi.wsapi.v1.bygning.domain.bygning
set nsmap_domain_bygning_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/bygning/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.bygning.domain.bygning.koder
set nsmap_domain_elektronisktinglysing=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/elektronisktinglysing,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.elektronisktinglysing
set nsmap_domain_endringslogg=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/endringslogg,no.statkart.matrikkel.matrikkelapi.wsapi.v1.endringslogg.domain.endringslogg
set nsmap_domain_endringslogg_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/endringslogg/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.endringslogg.domain.endringslogg.koder
set nsmap_domain_exception=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/exception,no.statkart.matrikkel.matrikkelapi.wsapi.v1.endringslogg.domain.exception
set nsmap_domain_forretning=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/forretning,no.statkart.matrikkel.matrikkelapi.wsapi.v1.forretning.domain.forretning
set nsmap_domain_geometri=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/geometri,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.geometri
set nsmap_domain_geometri_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/geometri/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.geometri.koder
set nsmap_domain_grunnforurensing=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/grunnforurensing,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.grunnforurensing
set nsmap_domain_grunnforurensing_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/grunnforurensing/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.grunnforurensing.koder
set nsmap_domain_jobb=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/jobb,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.jobb
set nsmap_domain_jobb_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/jobb/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.jobb.koder
set nsmap_domain_kart=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/kart,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.kart
set nsmap_domain_kodeliste=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/kodeliste,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.kodeliste
set nsmap_domain_kommune=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/kommune,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.kommune
set nsmap_domain_kommunetillegg=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/kommunetillegg,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.kommunetillegg
set nsmap_domain_kommunetillegg_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/kommunetillegg/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.kommunetillegg.koder
set nsmap_domain_konsesjon=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/konsesjon,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.konsesjon
set nsmap_domain_konsesjon_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/konsesjon/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.konsesjon.koder
set nsmap_domain_kulturminne=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/kulturminne,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.kulturminne
set nsmap_domain_kulturminne_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/kulturminne/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.kulturminne.koder
set nsmap_domain_matrikkelenhet=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/matrikkelenhet,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.matrikkelenhet
set nsmap_domain_matrikkelenhet_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/matrikkelenhet/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.matrikkelenhet.koder
set nsmap_domain_person=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/person,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.person
set nsmap_domain_person_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/person/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.person.koder
set nsmap_domain_rapport=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/rapport,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.rapport
set nsmap_domain_rapport_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/rapport/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.rapport.koder
set nsmap_domain_sefrak=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/sefrak,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.sefrak
set nsmap_domain_sefrak_koder=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/sefrak/koder,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.sefrak.koder
set nsmap_domain_util=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/util,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.util
set nsmap_domain_metadata=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/domain/metadata,no.statkart.matrikkel.matrikkelapi.wsapi.v1.domain.metadata
set nsmap_domain_exception=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/exception,no.statkart.matrikkel.matrikkelapi.wsapi.v1.exception

set nsmap_service_adresse=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/adresse,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.adresse
set nsmap_service_aktivitetsliste=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/aktivitetsliste,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.aktivitetsliste
set nsmap_service_bruker=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/bruker,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.bruker
set nsmap_service_bygning=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/bygning,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.bygning
set nsmap_service_forretning=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/forretning,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.forretning
set nsmap_service_grunnforurensing=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/grunnforurensing,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.grunnforurensing
set nsmap_service_kodeliste=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/kodeliste,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.kodeliste
set nsmap_service_kommune=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/kommune,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.kommune
set nsmap_service_konsesjon=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/konsesjon,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.konsesjon
set nsmap_service_kulturminne=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/kulturminne,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.kulturminne
set nsmap_service_matrikkelenhet=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/matrikkelenhet,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.matrikkelenhet
set nsmap_service_matrikkelsok=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/matrikkelsok,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.matrikkelsok
set nsmap_service_nedlastning=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/nedlastning,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.nedlastning
set nsmap_service_person=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/person,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.person
set nsmap_service_rapport=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/rapport,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.rapport
set nsmap_service_sefrak=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/sefrak,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.sefrak
set nsmap_service_store=/n:http://matrikkel.statkart.no/matrikkelapi/wsapi/v1/service/store,no.statkart.matrikkel.matrikkelapi.wsapi.v1.service.store

set nsmap_domain_all=%nsmap_domain% %nsmap_domain_adresse% %nsmap_domain_adresse_koder% %nsmap_domain_aktivitetsliste% %nsmap_domain_aktivitetsliste_koder% %nsmap_domain_bruker% %nsmap_domain_bruker_koder% %nsmap_domain_bygning% %nsmap_domain_bygning_koder% %nsmap_domain_elektronisktinglysing% %nsmap_domain_endringslogg% %nsmap_domain_exception% %nsmap_domain_metadata% %nsmap_domain_endringslogg_koder% %nsmap_domain_forretning% %nsmap_domain_geometri% %nsmap_domain_geometri_koder% %nsmap_domain_grunnforurensing% %nsmap_domain_grunnforurensing_koder% %nsmap_domain_jobb% %nsmap_domain_jobb_koder% %nsmap_domain_kart% %nsmap_domain_kodeliste% %nsmap_domain_kommune% %nsmap_domain_kommunetillegg% %nsmap_domain_kommunetillegg_koder% %nsmap_domain_konsesjon% %nsmap_domain_konsesjon_koder% %nsmap_domain_kulturminne% %nsmap_domain_kulturminne_koder% %nsmap_domain_matrikkelenhet% %nsmap_domain_matrikkelenhet_koder% %nsmap_domain_person% %nsmap_domain_person_koder%  %nsmap_domain_rapport_koder% %nsmap_domain_sefrak% %nsmap_domain_sefrak_koder% %nsmap_domain_util% %nsmap_service_adresse% %nsmap_service_aktivitetsliste% %nsmap_service_bruker% %nsmap_service_bygning% %nsmap_service_forretning% %nsmap_service_grunnforurensing% %nsmap_service_kodeliste% %nsmap_service_kommune% %nsmap_service_konsesjon% %nsmap_service_kulturminne% %nsmap_service_matrikkelenhet% %nsmap_service_matrikkelsok% %nsmap_service_nedlastning% %nsmap_service_person% %nsmap_service_rapport% %nsmap_service_sefrak% %nsmap_service_store%

svcutil /out:WebServiceProxy.cs /serializer:XmlSerializer /config:App.config %nsmap_domain_all%  wsdls\*.xsd wsdls\*.wsdl

Denne kjøringen krever at man har lastet ned zip-filen i en underkatalog med navn wsdls. Hvis man ikke erstatter teksten "REPLACE_WITH_ACTUAL_URL" i port-elementene i wsdl-ene med en ekste URL vil man få feilmeldinger under genereringen på dette og man vil mangle transport-egenskapen i app.config, men den genererte koden blir ok. Det kan derfor være lurt å legge inn en URL i wsdl-filene under generering og så skille dette ut i en property senere for å kunne konfigurere dette som man vil.

Bygge og kjøre .NET eksempelklient

Steg for steg bekrivelse av hvordan .NET eksempelklienten bygges.

Klientprosjektet lastes ned fra siden:

https://matrikkel.no/matrikkelapi/wsapi/v1/dokumentasjon/matrikkelAPI-v1-dotnetClient.zip

Åpne Visual Studio "Developer Command Prompt"
Naviger til roten av .NET eksempelklientprosjektet
Sett opp domain-mappings som beskrevet i seksjon "Eksempel 2:.NET". Siste kommando er set nsmap_domain_all=%nsmap_domain% ...
Bytt ut "REPLACE_WITH_ACTUAL_URL" i WSDL-ene med ekte URL. Dette er ikke strengt nødvendig for å få eksempelklienten til å fungere, men man vil få feilmelding under generering av proxy-filen dersom man ikke gjør dette.
Lag proxyfil og legg til servicepunkter i App.config med kommando (merk at versjonsnummer og path kan være annerledes på din maskin):

"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools\x64\SvcUtil.exe" ^
  /out:WebServiceProxy.cs ^
  /serializer:XmlSerializer ^
  /mergeConfig ^
  /config:App.config ^
  %nsmap_domain_all% wsdl\*.xsd wsdl\*.wsdl

Legg proxyfila WebServiceProxy.cs til prosjektet.
Eksempelklienten har satt systemVersion til trunk. Dette betyr at man får ut de nyeste feltene fra API-et. Dersom man ønsker å teste en spesifikk versjon må dette endres i app.config <add key="SystemVersion" value="3.17.0"/>
Bygg prosjektet med kommando msbuild
Kjør Eksempelklienten med kommando bin\Debug\MatWSTester.exe. Url og credentials oppgis ved start, alternativt settes i filen App.config. Bruk da eksempelvis https://matrikkel.no/matrikkelapi/wsapi/v1/ (prod) eller https://prodtest.matrikkel.no/matrikkelapi/wsapi/v1/ (prodtest) som endpoint adresse.

Kjøring av kall mot API-et

Etter at koden er generert for webtjenesteklienten blir det neste steget å kalle på tjenestene.

Eksempel for Java

AdresseService service = new AdresseServiceWS().getAdresseServicePort(); // Oppretter instansen vår

BindingProvider provider = (BindingProvider)service;
provider.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL); // Bytt ut med ekte URL
provider.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, username);            // Bytt ut med faktisk brukernavn
provider.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);            // Bytt ut med faktisk passord

VegadresseId id = service.findAdresseIdForIdent(new VegadresseIdent(), new MatrikkelContext());

Koden over gir oss tilgang til en tjeneste, setter URL, brukernavn og passord på tjenesten og utfører så et enkelt kall (med ikke-fullstendige parametre).

Nedlasting av WSDL-filer​

Bygging av klienter fra WSDL​

Eksempel 1: wsimport for Java​

Eksempel 2: .NET​

Bygge og kjøre .NET eksempelklient​

Kjøring av kall mot API-et​

Eksempel for Java​