-
Notifications
You must be signed in to change notification settings - Fork 2
04. API for eksamen.udir.no
Alle URL'er listet i denne seksjonen er relative til en base basert på hvilket miljø som benyttes. Det er satt opp et dedikert miljø for SAS og det anbefales at man benytter dette miljøet fremfor andre når det er snakk om testing av API'et som tilbys mot SAS'ene. SAS-miljøet ligger på https://eksamen-sas.udir.no/sas/ og https://eksamenapi-sas.udir.no/sas/. APIet er dokumentert med swagger og finnes her: https://eksamenapi-sas.udir.no/swagger
Med unntak av domenespesifikke ord (f.eks eksamen, eksamensdel m.m.) vil vi som hovedregel benytte engelsk språk.
API krever XML på payload som skal sendes inn, men tilbyr både JSON og XML på responser fra API'et. Standard format på payload som returneres er JSON, dersom man ønsker XML spesifiseres det med header:
Accept: application/xml
Oppdaterte XSD for produksjonsmiljøet kan alltid lastes ned fra:
https://eksamenapi.udir.no/sas/skjema
Oppdaterte XSD for testmiljøet kan alltid lastes ned fra:
https://eksamenapi-sas.udir.no/sas/skjema
All input fra SAS vil bli validert mot et sett med xsd skjemaer. Resursen returnerer en ZIP-fil med valideringsskjemaene som benyttes til å validere payload sendt inn til API'et på de ulike ressursene.
Returnerer 200 OK
Krever ikke autentisering.
Returnerer eksamensplanen for inneværende periode. Datamodellen for dataene som returneres i payload på respons på tjenesten finnes her. Standard format på payload som returneres er JSON, dersom man ønsker XML spesifiseres det med Accept: application/xml
eksamensperiode kan settes til enten H-2015 eller V-2016 for hhv høst 2015 og vår 2016
opplaeringsniva kan settes til enten VGS eller GS for hhv videregående og grunnskole
skoleorgno kan settes til organisasjonsnummer for en gitt skole. Dette er for å få ut eksamener (varianter) som er tilgjengelig for et begrenset antall skoler.
Returnerer 200 OK
Krever ikke autentisering.
Returnerer eksamensplanen for inneværende periode. Datamodellen for dataene som returneres i payload på respons på tjenesten finnes her. Standard format på payload returneres som JSON, dersom man ønsker XML spesifiseres det med Accept: application/xml
eksamensperiode kan settes til enten H-2017 eller V-2018 for hhv høst 2017 og vår 2018
skoleorgno kan settes til organisasjonsnummer for ønsket skole. Med dette får du unike eksamener (varianter) som et begrenset antall skoler har ansvar for og kan melde seg opp i.
Returnerer 200 OK
Krever ikke autentisering.
Foreta påmelding med XML payload som beskriver kandidatene som skal meldes på. I responsen vil det returneres en guid som igjen kan benyttes for å hente status på en gitt påmelding. Datamodellen som skal benyttes ifm påmelding er illustrert her.
Spesielle fagkoder
NOR0214/NOR0215
Påmelding til disse fagkodene krever at påmeldingen man sender inn inneholder påmelding til både NOR0214 og NOR0215 for en gitt kandidat.
NOR1415
Påmelding til denne fagkoden krever at påmeldingen man sender inn ikke inneholder påmelding til NOR0214 eller NOR0215 for en gitt kandidat man ønsker å melde på til NOR1415.
REA3015
Påmelding til denne fagkoden krever at man spesifiserer hvilken variant man ønsker å melde en kandidat på til. En kandidat kan bare meldes på i èn av variantene. Variantene som er tilgjengelig er følgende:
- JAV, som representerer Informasjonsteknologi 2 Java
- AS, som representerer Informasjonsteknologi 2 Action Script
- CS, som representerer Informasjonsteknologi 2 C Sharp
- DIV, som representerer Informasjonsteknologi 2 diverse språk
Returnerer 202 Accepted
Krever autentisering.
Med referansen fra ~/api/ekstern/kandidatpamelding kan man benytte denne ressursen for å hente ut en gitt status på en påmelding. Datamodellen som returneres som rapport er illustrert
her. Standard format på payload som returneres er JSON, dersom man ønsker XML spesifiseres det med Accept: application/xml.
Returnerer 200 OK
Krever autentisering.
Mulighet for å hente ut liste over påmeldte kandidater på en gitt skole uavhengig av om de er meldt på via integrasjonen eller manuelt i grensesnittet i eksamenstjenesten. Man må oppgi organisasjonsnummeret til skolen (orgno) og eksamensperiodekode (periodekode). Periodekoden er typisk en sammensetning av semester og år, eksempel: H-2015. Periodekoden vil være den man får ut når man henter eksamensplanen. Datamodellen som returneres er illustrert
her. Standard format på payload som returneres er JSON, dersom man ønsker XML spesifiseres det med Accept: application/xml.
Returnerer 200 OK
Krever autentisering.
Mulighet for å slette en påmeldt kandidat på en gitt skole og fagkode uavhengig av om kandidaten er meldt på via integrasjonen eller manuelt i grensesnittet.
Følgende parametre må oppgis:
- Kandidatnummeret til den påmeldte kandidaten(kandidatnummer). Kandidatnummeret til kandidatene følger med resultatet fra ressursen: ~/kandidat?orgno={orgno}&periodekode={periodekode}
- Fagkoden kandidaten er meldt opp i (fagkode). Fagkoden er den som følger med resultaten fra ressursen ~/kandidat?orgno={orgno}&periodekode={periodekode}
- Organisasjonsnummeret til skolen (orgno)
- Eksamensperiodekode (periodekode). Periodekoden er typisk en sammensetning av semester og år, eksempel: H-2015. Periodekoden vil være den man får ut når man henter eksamensplanen.
Datamodellen som returneres er illustrert her
Returnerer 200 OK
Krever autentisering.
Mulighet for å slette flere påmeldte kandidat på en gitt skole og fagkode uavhengig av om kandidaten er meldt på via integrasjonen eller manuelt i grensesnittet.
Følgende parametre må oppgis:
- Organisasjonsnummeret til skolen (orgno)
- Eksamensperiodekode (periodekode). Periodekoden er typisk en sammensetning av semester og år, eksempel: H-2015. Periodekoden vil være den man får ut når man henter eksamensplanen.
- Liste av kandidat-fagkode par som formatert som Json sendt som data. eks: [ { Kandidatnummer: "1234", Fagkode: "NOR1415" } , { Kandidatnummer: "1234", Fagkode: "NOR1415" } ]
Datamodellen som returneres er illustrert her.
Returnerer 200 OK
Krever autentisering.
Ressurs: ~/karakteroversikt?orgno={orgno}&periodekode={periodekode}&sasBrukerReferanse={sasBrukerReferanse}
Mulighet for å hente ut liste over kandidatenes deltakelsesstatus og karakter på en gitt skole. Dersom det foreligger klagekarakter og -begrunnelse vil man også kunne hente ut det herifra.
Man må oppgi følgende parametre:
- Organisasjonsnummeret til skolen (orgno)
- Eksamensperiodekode (periodekode). Periodekoden er typisk en sammensetning av semester og år, eksempel: H-2015. Periodekoden vil være den man får ut når man henter eksamensplanen.
- SasBrukerReferanse (sasBrukerReferanse). SasBrukerReferanse settes til brukernavnet i PAS.
I tillegg kan man sette parameteret ?includeEksamenAvlystStatus=true (valgfritt å bruke). Dersom dette parameteret settes vil man få deltakelsesstatusen "EA" (eksamen avlyst) for kandidatpåmeldinger som har fått avlyst eksamen. Dersom det ikke settes vil man få deltakelsesstatusen "DF" (dokumentert fravær) for disse kandidatpåmeldingene.
Datamodellen som returneres er illustrert her. Standard format på payload som returneres er JSON, dersom man ønsker XML spesifiseres det med Accept: application/xml.
Returnerer 200 OK
Krever autentisering.
Ressurs: ~/sensoroppdrag/{organisasjonsnummer}/{eksamensperiodekode} (kun tilgjengelig på https://eksamenapi-sas.udir.no/sas/)
Følgende parametre må oppgis:
- Organisasjonsnummeret til skolen (organisasjonsnummer)
- Eksamensperiodekode (eksamensperiodekode). eksamensperiodekode er en sammensetning av semester og år, eksempel: V-2018. eksamensperiodekoden vil være den man får ut når man henter eksamensplanen.
Returnerer en liste med personer som er oppnevnt som fagperson ved skolen. Hver fagperson har en liste over fagkoder personen er oppnevnt som sensor i og en liste over fagkoder personen er oppnevnt som klagenemndsmedlem i. Format på payloaden som returneres er JSON. Datamodellen finnes her
Returnerer 200 OK.
Krever autentisering.
Feil forårsaket av regelbrudd ved for eksempel påmelding vil man kunne lese ut fra StatusMessage på en gitt kandidat. Tjenerfeil returneres med statuskode 500 og en melding i payloaden av responsen. Meldingen vil se slik ut:
<ApiError>
<Message>Failed to process request. Exception logged on server with reference {guid}. Contact PAS system administrators.<Message/>
<ApiError/>{guid} er her en unik referanse som vi legger på loggen på serveren slik at vi skal finne tilbake til feilen som skjedde.
Når man sender inn en påmelding til eksamenssystemet vil det foretas en validering av denne forespørselen før man gir en kvittering tilbake på at påmeldingen er mottatt og vil bli prossesert. Følgende områder vil bli validert og gi en umiddelbar tilbakemelding som en ApiError og HTTP status kode 400:
- eksamensperiodekoden må være gyldig
- dersom man har spesifisert en epostadresse for eventuelle feil må det være en gyldig adresse
- alle fødselsnummer for kandidater må være gyldige
- fagkoder spesifisert for påmeldingen må være gyldige i den aktive eksamensplanen (~api/ekstern/eksamensplan)
- navn på kandidatgruppe må være unikt innenfor en gitt fagkode på en skole
Når man sender inn en påmelding til eksamenssystemet vil det bli foretatt en vask mot det sentrale folkeregister av navnet til kandidaten. Dette blir kun gjort om det navnet som sendes med påmeldingen fra SAS ikke stemmer overens med det navnet eksamenssystemet eventuelt allerede har lagret på gjeldende kandidat. Hvis man ønsker å teste dette i testmiljøet (https://eksamen-sas.udir.no) er det kun et sett med predefinerte brukere som finnes i det sentrale folkeregister sin testtjeneste. Se https://qa.infotorg.no/test/cms/site/0/page?id=77 for mer informasjon.