Results API 2.0.1

Results API 2.0.1

Titel

Results API

Status

Final - Deprecated

Versie

Documentatie: 2.0.1

schemaVersion: 2.0.0

Datum

15 September 2025

Auteur

Werkgroep Toetsen en examineren

De Results API wordt gebruikt om leerresultaten te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Leerresultaten met het Digitaal toetssysteem of Gebruiksomgeving digitale leermiddelen als Verzender.

Scope: werkingsgebieden funderend onderwijs en vavo

De afspraken met betrekking tot het administreren van leerresultaten zijn van toepassing op de werkingsgebieden:

  • Primair onderwijs

  • Gespecialiseerd onderwijs

  • Voortgezet onderwijs

  • Voortgezet algemeen volwassenenonderwijs (vavo)

De gegevensdiensten zijn niet ontwikkeld voor het middelbaar beroepsonderwijs. In het middelbaar beroepsonderwijs wordt gebruik gemaakt van Onderwijs Koppelingen Examinering.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst

  • Leerresultaten

Scopes

  • eduv.result

Entiteiten

Verzender

  • Digitaal toetssysteem

  • Gebruiksomgeving digitale leermiddelen

Ontvanger

  • Administratiesysteem leerresultaten

  • Leermiddelendashboard

Endpoints

Administratiesysteem leerresultaten

Leermiddelendashboard

POST /results

Operatie met endpoint POST /results in het koppelvak van Administratiesysteem leerresultaten of Leermiddelendashboard wordt door het Digitaal toetssysteeem aangeroepen:

Operatie en endpoint

POST /results

Operatie en endpoint

POST /results

OperatieID

postResults

Samenvatting

Het verzoek om bij het ontvangende systeem de toetsscores & -resultaten te verwerken voor een individuele onderwijsdeelnemer of groep van onderwijsdeelnemers.

Beschrijving

Lijst van score & resultaat items per onderwijsdeelnemer, met het verzoek nieuwe scores/resultaten te creëren of bestaande scores/resultaten te wijzigen. Het bericht is ingericht op groepsgewijze aanlevering of aanlevering van individuele onderwijsdeelnemer. Bij de lijst is algemene informatie gevoegd zoals toets/examen, afnamemoment en opmerkingen.

Tags

Administratiesysteem leerresultaten
Leermiddelendashboard

Parameters bij request

-

Object in request body

Object AssessmentScoresAndResults, met onderliggende objecten StudentScoresAndResults, Assessment en ScoreScale.

Antwoorden (statuscodes)

201 (Created): “Het verzoek is geaccepteerd de verwerking heeft plaatsgevonden; dit heeft tot de creatie van een resource geleid.“
In dit geval gaat het om volledige ontvangst, acceptatie en verwerking van het gehele bericht. Is er afwijzing op basis van een onderdeel van het bericht dan wordt het hele bericht afgewezen. Bij grote berichten kan een afwijzing lastig zijn voor de verzender; mogelijke oplossing is het bericht dan in stukken te verzenden.

202 (Accepted): “Het verzoek is geaccepteerd voor verwerking, maar de verwerking heeft nog niet plaatsgevonden; in feite zou de verwerkingen nog niet gestart kunnen zijn. De verwerking zal later wel of niet plaatsvinden, waarbij het verzoek bij de verwerking eventueel zou kunnen worden afgewezen.“
Ontvanger heeft nog geen mechanisme om fouten die bij de verwerking naar voren komen terug te melden aan verzender (bijvoorbeeld een bericht met het verwerkingsresultaat sturen naar verzender). Verzender heeft nog geen mechanisme om de verwerking te controleren (bijvoorbeeld een specifiek onderdeel uit het bericht opvragen bij ontvanger).

In deze eerste versie kunnen ontvangende systemen alleen terugkoppeling geven op bericht niveau. Ofwel, een bericht is volledig geaccepteerd (202 of 201), of een bericht is volledig geweigerd (400). Fouten die door middel van HTTP-resultaatcodes 400, 401 en 403 kunnen worden teruggeven, hebben dus alleen betrekking op het bericht. Niet op de individuele resultaten.