Allmän information

Inspera Assessment API är en uppsättning öppna REST-API:er som gör det möjligt för externa system att få åtkomst till en delmängd av funktionaliteten i Inspera Assessment genom att använda användarbehörigheter i systemet. Funktionaliteten inkluderar att skapa och uppdatera tentatillfällen, tilldela och ta bort studenter/elever och medverkande från tentatillfällen, exportera resultat och svar efter bedömning, samt användarhantering.

Vi utvecklar, uppdaterar och lägger till nya API:er löpande. Alla ändringar och tillägg i befintliga API:er, såväl som nyutvecklade API:er och planer för API-vägkartor, meddelas via Insperas versionsanteckningar (release notes). Se vår produktsida för att lära dig hur du prenumererar på versionsanteckningar. 

Designprinciper

Insperas API:er är utformade utifrån följande kärnprinciper:

• Inspera API:er tillhandahåller slutpunkter (endpoints) för att skicka (push) och hämta (pull) data
• Inspera Webhooks tillhandahåller utgående aviseringar om händelser i Insperas tjänster
• Både API:er och Webhooks är utformade för att vara generellt återanvändbara – utan tät koppling till externa system:
  • Integrationslager ligger vanligtvis mellan Inspera API/Webhooks och externa tjänster för att hantera nödvändig konvertering för att säkerställa systeminteroperabilitet
• OAuth används för autentisering
• Auktorisering hanteras via samma behörighetsmodell som används i resten av tjänsten Inspera Assessment

Inspera API:er i kundens systemlandskap

Illustration av hur Inspera API:er passar in i kundens systemlandskap för högre utbildning (klicka på bilden för att öppna i full storlek i en ny flik).

Komma igång

Första stegen

För att komma igång behöver du en användare i Inspera Assessment med administratörsbehörighet. Från användarprofilen kommer du sedan att kunna få åtkomst till API-nyckeluppgifter för antingen dig själv eller andra Inspera-användare i din organisation. Dessa auktoriseringsuppgifter inkluderar en API-nyckel (authorization code). Utöver denna kod behövs ett "client_id" för att kunna skicka API-anrop för att erhålla en autentiseringstoken. Detta förklaras senare i detta dokument.

API-nyckeln kommer att vara tillgänglig endast en gång. Om en användare förlorar eller glömmer sin API-nyckel kan valfri administratör för din organisation återkalla användarens åtkomst och generera en ny kod åt dem.

Information

Generering av API-nycklar kan endast göras av användare som har rollen Användaradministratör (User Admin).

Anrop som görs med en given API-nyckel kommer att följa samma behörigheter som det länkade användarkontot har. Detsamma gäller för Webhook-aviseringar. Vi rekommenderar starkt att ni skapar dedikerade integrationsanvändare på er Inspera Assessment-instans och använder API-nycklar från dessa användare för integrationsanrop. Detta för att göra integrationen oberoende av personliga användarkonton.

Var finns API-nyckeln i Inspera Assessments användargränssnitt?

Öppna "Användaradministration" från huvudmenyn i Inspera Assessment och sök efter den användare du vill generera en nyckel för. Följande visas på skärmen:

Efter att ha klickat på "Generate API authorization code":

När du lämnar användarvyn kommer API-nyckeln aldrig att visas igen. En ny nyckel kan endast skapas efter att åtkomsten har återkallats:

Hur erhåller man client_ID?

"client_ID" är en parameter som behövs för att rätt åtkomsttoken ska kunna genereras. Detta värde är i de flesta fall den första delen av domänen i er URL för Inspera Assessment (host-part). Om er Inspera-URL till exempel är https://test.inspera.com/, kommer client_id att vara "test". Detta gäller dock inte för alla klienter; om det inte fungerar, vänligen kontakta Service Desk.

När en användare har sin auktoriseringskod och har erhållit sitt client_id kan de börja använda API:erna.

Göra API-anrop

API:erna som listas nedan är tillgängliga via HTTPS-anrop (se den specifika API-dokumentationen för detaljer).

För att erhålla en access token (åtkomsttoken) ska ett anrop göras i följande format:

curl -d "" -H "code:<din API-auktoriseringskod>" "https://<din inspera-domän>/api/authenticate/token/ ?grant_type=authorization_code&client_id=<ditt client_id>"

Alla API:er förutsätter en base url i följande format:

https://<din inspera-domän>/api

1. Nyckel (Key)	Värde (Value)
   URL	/api/authenticate/token/
   Metod (Method)	POST
   URL-parametrar: *obligatorisk
   grant_type*	authorization_code
   client_id*	(string), se ovan för mer information om hur du erhåller denna uppgift
   HEADER-parametrar: *obligatorisk
   code*	(string)
   Dataparametrar: (obligatorisk för POST)
   Content-Type	application/x-www-form-urlencoded
   Svar (Responses):
   200	Lyckat (Success) Returnerar:  { "access_token": string, "expires_in": integer }
   400	Fel: Ogiltig begäran (Bad request) Returnerar: { "error": [OAuth2Exception] }
   401	Fel: Obehörig (Unauthorized) Returnerar: { "error": "invalid_grant" }
   409	Fel: Konflikt (Conflict) Returnerar: { "error": "Multiple tokens for user", "description": "Please contact inspera support" }
   500	Fel: Internt serverfel (Internal server error) Returnerar: { "error": "Internal error authenticating user", "description": "Please contact inspera support" }
   501	Fel: Inte implementerat (not implemented)

Exempelscenario med kommandoradsverktyg för autentisering och hämtning av provresultat

Nedan går vi igenom hur man använder API:et från kommandoraden, förutsatt att verktyget curl är installerat. Eftersom alla meddelanden är i JSON-format är verktyget jq också mycket användbart för färgkodning och enkel datautvinning när man arbetar från kommandoraden eller i skalskript.

Detta scenario täcker inte alla detaljer – se den faktiska API-dokumentationen för specifikationer om format för begäranden och svar.

Exempel

Nödvändiga data som används i detta exempel:

Steg 1: Autentisera och erhåll åtkomsttoken

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

Notera:

Alternativet -d "" gör att curl skickar en POST-begäran med tom body och content type application/x-www-form-urlencoded, vilket autentiserings-API:et kräver.

Om anropet lyckas returneras en JSON som innehåller en "access bearer token" (i detta exempel: "xyz-abcd-efg" och en livslängd i sekunder).

Svaret kommer att se ut så här:

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

Steg 2: Skicka API-anrop

1. I detta exempel görs ett API-anrop för att hämta metadata för ett prov med testID=12312312 med hjälp av detta API: https://ia.inspera.no/apidoc/#/test/getTestMetadata

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

   Eller, om vi vill fånga upp åtkomsttoken direkt från kommandoraden, kan vi använda jq för att lagra den som en miljövariabel och återanvända den:

   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 detta exempel görs ett API-anrop för att exportera resultat för en student/elev på ett givet prov med hjälp av detta API: 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

   Eftersom detta API kan hämta en betydande mängd data kommer det, istället för omedelbara resultat, att returnera en callback-URL:

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

   Att utföra en GET mot denna returnerar antingen status för exporten eller, när den är klar (vanligtvis under 5 s), en kortlivad URL för att ladda ner JSON-filen för exporten.

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

   Slutligen kan administratören använda den tillhandahållna URL:en för att ladda ner och använda exporten av provresultaten.