Kom i gang med Inspera Assessment API

  • Oppdatert

Generell informasjon

Inspera Assessment API er et sett med åpne REST-API-er som lar eksterne systemer få tilgang til en delmengde av funksjonaliteten i Inspera Assessment ved å bruke brukerrettighetene i systemet. Funksjonaliteten inkluderer oppretting og oppdatering av prøver, tildeling og fjerning av kandidater og bidragsytere fra prøver, eksport av resultater og besvarelser etter vurdering, samt brukeradministrasjon.

Vi utvikler, oppdaterer og legger til nye API-er fortløpende. Alle endringer og tillegg i eksisterende API-er, samt nyutviklede API-er og planer for veikart, kunngjøres gjennom Insperas versjonsnotater (release notes). Vennligst se vår produktside for informasjon om hvordan du abonnerer på versjonsnotater. 

Designprinsipper

Insperas API-er er designet basert på følgende kjerneprinsipper:

  • Inspera API-er tilbyr endepunkter for å sende (push) og hente (pull) data
  • Inspera Webhooks gir utgående varslinger om hendelser i Insperas tjenester
  • Både API-er og Webhooks er designet for å være generelt gjenbrukbare – uten tett kobling mot eksterne systemer:
    • Integrasjonslag ligger vanligvis mellom Inspera API/Webhooks og eksterne tjenester for å håndtere nødvendig konvertering for å sikre samhandling mellom systemer
  • OAuth brukes til autentisering
  • Autorisasjon håndteres gjennom den samme tillatelsesmodellen som brukes i resten av Inspera Assessment-tjenesten

Inspera API-er i kundens systemlandskap

Illustrasjon av hvordan Inspera API-ene passer inn i kundens systemlandskap for høyere utdanning (klikk på bildet for å åpne i full størrelse i en ny fane).

API1.png

Kom i gang

Første steg

For å komme i gang trenger du en bruker i Inspera Assessment med administratorrettigheter. Fra brukerprofilen vil du da kunne få tilgang til API-nøkkeldetaljer for enten deg selv eller andre Inspera-brukere i din organisasjon. Disse detaljene inkluderer en API-nøkkel (authorization code). I tillegg til denne koden trenger du en "client_id" for å kunne sende API-kall for å hente ut autentiseringstoken. Dette forklares senere i dokumentet.

API-nøkkelen vil være tilgjengelig kun én gang. Hvis en bruker mister eller glemmer API-nøkkelen sin, kan en administrator for organisasjonen trekke tilbake brukerens tilgang og generere en ny kode.

Informasjon

Generering av API-nøkler kan kun gjøres av brukere som har rollen Brukeradministrasjon (User Admin).

Kall som gjøres med en gitt API-nøkkel vil følge de samme rettighetene som den tilknyttede brukerkontoen har. Det samme gjelder for Webhook-varslinger. Vi anbefaler sterkt å opprette dedikerte integrasjonsbrukere på deres Inspera Assessment-instans, og bruke API-nøkler fra disse brukerne til integrasjonskall. Dette er for å gjøre integrasjonen uavhengig av personlige brukerkontoer.

Hvor finner jeg API-nøkkelen i grensesnittet til Inspera Assessment?

Åpne "Brukeradministrasjon" fra hovedsiden i Inspera Assessment og søk etter brukeren du vil generere en nøkkel for. Følgende vil vises på skjermen:

2023-10-18_16h11_44.png

Etter å ha klikket på "Generate API authorization code":

2023-10-18_16h13_20.png

Etter at du har lukket brukervinduet, vil API-nøkkelen aldri vises igjen. En ny nøkkel kan kun genereres etter at den eksisterende tilgangen er trukket tilbake:

2023-10-18_16h14_00.png

Hvordan skaffe client_ID?

"client_ID" er en parameter som trengs for at korrekt tilgangstoken skal kunne genereres. Denne verdien er i de fleste tilfeller den første delen av domenet i deres URL for Inspera Assessment (host-part). For eksempel, hvis deres Inspera-URL er https://test.inspera.com/, vil client_id være "test". Dette gjelder imidlertid ikke for alle klienter; dersom det ikke fungerer, vennligst kontakt Service Desk.

Når en bruker har sin "authorization code" og har funnet sin "client_id", kan de begynne å bruke API-ene.

Gjøre API-kall

API-ene listet nedenfor er tilgjengelige via HTTPS-forespørsler (se den spesifikke API-dokumentasjonen for detaljer).

For å hente access token (tilgangstoken), skal et kall gjøres i følgende format:

curl -d "" -H "code:<din bruker-API-autorisasjonskode>" "https://<ditt inspera-domene>/api/authenticate/token/ ?grant_type=authorization_code&client_id=<din client_id>"

Alle API-ene forventer en base-url i følgende format:

https://<ditt inspera-domene>/api

  1. Nøkkel (Key) Verdi (Value)
    URL /api/authenticate/token/
    Metode (Method) POST

    URL-parametre:

    *påkrevd

    		  
    grant_type* authorization_code
    client_id* (string), vennligst se ovenfor for detaljer om hvordan du finner denne informasjonen

    HEADER-parametre:

    *påkrevd

    		  
    code* (string)

    Dataparametre:

    (påkrevd for POST)

    		  
    Content-Type application/x-www-form-urlencoded
    Responser:  
    200

    Vellykket (Success)

    Returnerer: 

    {
    "access_token": string,   
    "expires_in": integer
}
    400

    Feil: Ugyldig forespørsel (Bad request)

    Returnerer:

    {
    "error": [OAuth2Exception]
}
    401

    Feil: Uautorisert (Unauthorized)

    Returnerer:

    {
    "error": "invalid_grant"
}
    409

    Feil: Konflikt (Conflict)

    Returnerer:

    {
    "error": "Multiple tokens for user",
    "description": "Please contact inspera support"
}
    500

    Feil: Intern serverfeil (Internal server error)

    Returnerer:

    {
    "error": "Internal error authenticating user",
    "description": "Please contact inspera support"
}
    501 Feil: Ikke implementert (not implemented)

Eksempel på scenario med kommandolinjeverktøy for autentisering og henting av prøveresultater

Nedenfor går vi gjennom bruk av API-et fra kommandolinjen, forutsatt at verktøyet "curl" er installert. Siden alle meldinger er i JSON-format, er verktøyet "jq" også veldig nyttig for fargekoding og enkel datauthenting når du jobber fra kommandolinjen eller i shell-skript.

Dette scenarioet dekker ikke alle detaljer – se den faktiske API-dokumentasjonen for spesifikasjoner om formatet på forespørsler og responser.

Eksempel

Nødvendig data brukt i dette eksempelet:

Felt Verdi
Brukerens autorisasjonskode (fra brukeradministrasjon i Inspera) 123456-7890-abcd-efgh
Inspera-domene demo.inspera.no
client_id demo

Steg 1: autentiser og hent tilgangstoken

curl -d "" -H "code:123456-7890-abcd-efgh" "https://demo.inspera.no/api/authenticate/token/?grant_type=authorization_code&client_id=demo"

Merk:

Parameteren -d "" gjør at curl sender en POST-forespørsel med tom body og content type application/x-www-form-urlencoded, noe autentiserings-API-et krever.

Hvis forespørselen er vellykket, vil dette returnere en JSON som inneholder en "access bearer token" (i dette eksempelet: "xyz-abcd-efg" og en levetid i sekunder).

Responsen vil se slik ut:

{
    "access_token": "xyz-abcd-efg",
    "expires_in": 3600
}

Steg 2: Send API-kall

  1. I dette eksempelet gjøres et API-kall for å hente metadata for en prøve med testID=12312312 ved å bruke dette API-et: https://ia.inspera.no/apidoc/#/test/getTestMetadata

    curl -H "Authorization: bearer xyz-abcd-efg" https://demo.inspera.no/api/v1/test/12312312

    Hvis vi ønsket å fange opp tilgangstokenet direkte fra kommandolinjen, kan vi bruke "jq" for å lagre det som en miljøvariabel og gjenbruke det:

    auth_response=$(curl -d "" -H "code:123456-7890-abcd-efgh" "https://demo.inspera.no/api/authenticate/token/?grant_type=authorization_code&client_id=demo")
token=$(echo "${auth_response}" | jq -r '.access_token')
curl -H "Authorization: bearer ${token}" https://demo.inspera.no/api/v1/test/12312312

  2. I dette eksempelet gjøres et API-kall for å eksportere resultater for en kandidat på en gitt prøve ved å bruke dette API-et: https://ia.inspera.no/apidoc/#/candidates/getCandidateResult

    test_id= 12312312

    user_id=987654

    curl -H "Authorization: bearer xyz-abcd-efg" https://demo.inspera.no/api/v1/candidates/result/12312312/987654

    Siden dette API-et kan hente en betydelig mengde data, vil det – i stedet for umiddelbare resultater – returnere en URL for tilbakekalling (callback URL):

    https://demo.inspera.no/api/v1/candidates/results/12312312/987654

    Ved å utføre en GET-forespørsel mot denne URL-en vil du få enten status for eksporten, eller – når den er ferdig (vanligvis under 5 sekunder) – en midlertidig URL for nedlasting av eksportens JSON-fil.

    curl -H "Authorization: bearer xyz-abcd-efg" https://demo.inspera.no/api/v1/candidates/results/12312312/987654

    Til slutt kan administrator ta den oppgitte URL-en for å laste ned og bruke eksporten av prøveresultatene.

Var denne artikkelen nyttig?

0 av 0 syntes dette var nyttig