Detaljer om bruk av API-er i IK-bygg

På denne siden finner du ekstra informasjon om bruk av de ulike API-ene som inngår i IK-bygg. Denne informasjonen dekker blant annet:

Generelt viktige ting å huske på ved bruk av API-ene
Særegenheter og begrensninger ved de ulike API-ene
Bruk av abonnement-nøkler for tilgang på API-ene

Eksempler på API-bruk i praksis

Hvordan hente ut spørsmål via `/Questions`

Eksempelet under viser hvordan man ber om "alle internkontrollspørsmål med ID og tilhørende spørsmålstekst". Spørringer mot /Questions gjøres via GraphQL, og eksempelet under er kun ett av mange mulige spørringer man kan sette sammen ved hjelp av GQL-spørringsspråket.

curl -X POST 'https://api.kommunalteknikk.no/Questions' \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'ocp-apim-subscription-key: <IK-bygg-abonnement-nøkkel>' \
 -d '{ "query": "query { questions { id questionText } }" }'

GraphQL-endepunkter kan påkalles på likt vis som de fleste andre endepunkter, men krever at man sender med en spørrings-body for å definere hva man spør etter. For mer info om GraphQL og mulighetene det tilbyr for spørringer sjekk ut dokumentasjonen her.

Standardiserte spørsmål for teknisk tilstandsgrad (ASSS)

En undergruppe av spørsmålene i IK Bygg er koblet til spørsmål i ASSS sin standardiserte sjekkliste og danner utganspunktet for å kunne vurdere teknisk tilstandsgrad.

Dersom man ønsker disse, kan man spesifisere følgende query-parameter:

curl -X POST 'https://api.kommunalteknikk.no/Questions' \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'ocp-apim-subscription-key: <IK-bygg-abonnement-nøkkel>' \
 -d '{ "query": "query { questions(where: { StandardizedByAsss: true }) { id } }" }'

Hvordan registrere bygninger via `/InternkontrollBuilding`

curl -X POST 'https://api.kommunalteknikk.no/Answers/<api-version>/InternkontrollBuilding/{buildingId}' \
-H 'Content-Type: application/json' \
-H 'ocp-apim-subscription-key: <IK-bygg-abonnement-nøkkel>' \
-d '{
      "organizationId": "string",
      "buildingInfo": {
        "buildingName": "string",
        "municipalityNumber": "string",
        "addresses": [
          {
            "streetAddressInfo": {
              "adressenavn": "string",
              "husnummer": 0,
              "adressekode": 0,
              "bokstav": "string"
            },
            "matrikkelInfo": {
              "gaardsnummer": 0,
              "bruksnummer": 0,
              "festenummer": 0,
              "seksjonsnummer": 0,
              "undernummer": 0
            },
            "postalInfo": {
              "postnummer": "string",
              "poststed": "string"
            },
            "bruksenhetsnumre": ["string"]
          }
        ]
      }
    }'

Hvordan sende inn besvarelser via `/Answers`

curl -X POST 'https://api.kommunalteknikk.no/Answers/<api-version>/Answers' \
-H 'Content-Type: application/json' \
-H 'ocp-apim-subscription-key: <IK-bygg-abonnement-nøkkel>' \
-d '[{
    "questionId": <spørsmål som bedvares>,
    "buildingId": "YOUR BUILDING ID HERE",
    "yesOrNoValue": <Yes | No>,
    "answeredBy": {
        "role": "Owner",
        "id": <Din interne ID for brukeren som besvarte.>
    },
    "improvementCostInThousandNok": 35,
    "comment": "Her er det ingen rutiner for ettersyn av brannalarmanlegget."
}, {
    "questionId": 256,
    "buildingId": <bygg ID som samsvarer med et tidligere registrert bygg>,
    "conditionValue": 1,
    "answeredBy": {
        "role": <User | Owner>,
        "id": <Hvis det ønskes å finne tilbake til hvem som besvarte. Brukes ikke av IK bygg>
    },
    "improvementCostInThousandNok": null,
    "comment": <valgfri kommentar>
}]'

Eksemplene tar utganspunkt i bruk curl-kommandoen som man finner i flere terminaler. API-ene fungerer derimot uavhengig av metode for å kalle på dem enten det er via fetch() eller axios i JavaScript, eller via visuelle brukergrensesnitt som Post Man.

En fullstendig oversikt over de ulike formatene for spørringer og responser man kan få tilbake, finnes i listen over API-endepunkter. Gå til Utforsk API-er eller velg et API fra menyen under for å finne detaljerte beskrivelser av de mulige respons- og spørrings-objektene.

Ting å huske på ved registrering av bygninger og svar på spørsmål

Husk å bruke riktig `OrganizationId`

OrganizationId skal samsvare med en av følgende avhengig av hvem som er bygningens eier:

fylkesnummeret til fylkeskommunen;
kommunenummeret til kommunen;
eller organisasjonsnummeret til en organisasjon.
OrganizationId avgjør hvem som eier bygningen og tilhørende svar. Det skiller seg dermed fra municipalityNumber under buildingInfo som er for å avgjøre bygningens geografiske lokasjon.

Bruk vegadresser der de ekisterer

I henhold til FOR-2009-06-26-864 Forskrift om eiendomsregistrering (matrikkelforskriften) er det ønskelig å identifisere eiendommer via vegadresse dersom eiendommen har fått dette tildelt. Ved bruk av API-et oppfordres det derfor om å identifisere bygningene som det svares for, via vegadresse (og bruksenhetsnummer). Om det er snakk om en spesifikk seksjon eller feste som ikke kan identifiseres unikt via vegadresse, kan man spesifisere matrikkeladressen.

IK Byggs datamodell baserer seg på Kartverkets standarder for adressering av bygg. For mer informasjon se Kartverkets Adresseveileder

Ting å huske på ved uthenting av spørsmål

API-et for internkontrollspørsmål tilbys i form av et GraphQL-endepunkt. Her er det tilgjengeliggjort en rekke måter å hente ut

Bygningstyper (BuildingTypes), Bygningsdeler (BuildingParts) og Ansvarsområder (ResponsibilityAreas) har et hierarkisk forhold til hverandre; en bygningstype med ID 331 vil være en "under-bygningstype" av bygningstypen med ID 33 og bygningstypen med ID 3. Når man ber om spørsmål som er tilknyttet en viss bygningstype, for eksempel ved å bruke argumentet where: { buildingTypeIDs: [33] }, vil man få med alle spørsmål som enten er tilknyttet bygningstypene 3, 33 eller en under-bygningstype av 33. Man får altså med alle spørsmål som potensielt kan være gjeldende for et bygg av bygningstypen/bygningsdelen som man spesifiserer i spørringen. Dersom denne implisitte oppførselen ikke ønskes, kan man bruke følgende argument i GraphQL-spørringen:
options: { includeOnlyExplicitIdMatches: true }.

I utgangspunktet vil man kun få ut "aktive" spørsmål, altså spørsmål som ikke har blitt arkivert, fra endepunktet.
Arkiverte spørsmål kan hentes ut ved å legge til argumentet options: { includeArchived: true } som del av GraphQL-spørringen.

Autentisering via abonnement-nøkler

For at man skal få lov til å etterspørre noe fra de ulike API-ene, er man nødt til å legge ved en gyldig abonnement-nøkkel i spørringen. Dette gjøres ved å legge på en "ocp-apim-subscription-key"-header i spørringen som vist i eksemplene ovenfor.

Nøkkelen finner man her i utvikler-portalen (krever at man er innlogget som en bruker med tilgang på IK-bygg). Dersom man er logget inn og har tilgang, vil det dukke opp to nøkler – en for vanlig bruk av API-ene og en for testing av API-ene dersom man behøver det. Dersom du ikke ser noen nøkkel for IK-bygg under dette avsnittet, betyr det at du enten ikke er logget inn eller at organisasjonen din ikke har blitt tildelt et IK-bygg-abonnement ennå.

Forskjell mellom Standard abonnement og Test-abonnement

De vanlige endepunktene og test-endepunktene er i all hovedsak identiske. De fungerer på samme vis slik at det skal være mulig å teste bruk av API-ene i et test-miljø uten å sende inn noe ukorrekt data til de "ekte" tjenestene og databasene. Legg likevel merke til forskjellene under:

Selv om spørsmål-API-et funker likt i test-miljøet, er det ikke sikkert at spørsmålene du får derfra like. Det kan være forskjeller i dataen mellom de to miljøene.
Det er ingen garanti for at data innsendt via test-versjonen av svar-API-et blir værende der i fremtiden. Forvent likevel å få den samme dataen ut som man nettopp sendte inn.
Tjenestene for testing kjører på mindre skalerte tjenere enn de som skal levere den ekte IK-bygg-tjenesten. Forvent derfor lengre responstid fra Test-endepunktene enn fra de ekte endepunktene.
Til tider kan det være endringer som er innført i Test-versjonen av API-ene, som ennå ikke er kommet ut i produksjon.