1. Mag het resultaat een Proof of Concept zijn, of is het de bedoeling dat deze in productie gaat draaien?

Doel voor 2021 is een pilot te gaan ontwikkelen van een OnderwijsXplorer. Daarbij wordt onderwijsaanbod-data van verschillende instellingen middels de OOAPI-standaard geleverd via de door SURF te ontwikkelen OOAPI-gateway.

Het te ontwikkelen gedeelte bij de instelling om OOAPI data aan te leveren (het OOAPI-endpoint) legt een basis voor het uitwisselen van allerlei onderwijsdata en mag een Proof of Concept zijn. De instelling heeft de mogelijkheid op eigen gelegenheid het OOAPI-endpoint verder te ontwikkelen tot een productie status en kan daarbij gebruik maken van de OOAPI-gateway en OnderwijsXplorer.

2. Is het de bedoeling dat productie data wordt aangeleverd? Of mag dit ook “test” data zijn?

Omdat het een pilot betreft, mag de data ook test data zijn. Je kunt ook besluiten productie data te gebruiken, omdat de meeste data publieke informatie betreft. Zorg er wel voor dat de productie data geanonimiseerd is in geval van de 'person' gegevens.

3. Zijn alle request parameters al verplicht te implementeren?

Alle request parameters moeten verplicht geïmplementeerd worden. Omdat we alleen endpoints vragen die publieke onderwijsaanbod-data leveren. Er zijn een paar uitzonderingen voor het gebruik van bepaalde waarde van parameters.

Zie deze pagina voor een overzicht van de endpoints: Datamodel v4 & Endpoints


Wat zijn de uitzonderingen?


Bij het endpoint /academic-sessions/{ID}/offerings:

  • attribuut type: verplicht: program & course. Optioneel: component

Bij het endpoint /associations:

  • attribuut type: verplicht: programOfferingAssociation, courseOfferingAssociation. Optioneel: componentOfferingAssociation
  • attribuut rol: verplicht: lecturer, coordinator. Optioneel: student, teaching assistant, guest

Bij het endpoint /offerings/{ID}:

  • attribuut expand: verplicht: program, programOffering, course, courseOffering, organization, academicSession. Optioneel: component

Bij het endpoint /offerings/{ID}/associations:

  • attribuut type: verplicht: programOffering, courseOffering. Optioneel: componentOffering
  • attribuut rol: verplicht: lecturer, coordinator. Optioneel: student, teaching assistant, guest

Bij het endpoint /organizations/{ID}/offerings:

  • attribuut type: verplicht: program & course. Optioneel: component

Bij het endpoint /persons:

  • attribuut affiliations: verplicht: employee. Optioneel: student, guest

Bij het endpoint /persons/{ID}/associations:

  • attribuut type: verplicht: programOffering, courseOffering. Optioneel: componentOffering
  • attribuut rol: verplicht: lecturer, coordinator. Optioneel: student, teaching assistant, guest

4. Welk deel van de code/oplossing moet onder opensource worden vastgelegd?

Het idee achter het open-source beschikbaar maken van de code is dat andere instellingen kunnen leren van de door jullie gekozen oplossing/architectuur. Daarbij is het concept het belangrijkste en kan jullie code dienen ter inspiratie voor anderen. In ieder geval de code die de OOAPI data ontsluit zou beschikbaar gesteld moeten worden. Alle overige code is wenselijk als dat door jullie zinvol wordt geacht in de door jullie gekozen oplossing. Hoe meer je anderen kunt meenemen in jullie architectuur, hoe beter.

5. Zijn alle aangesloten API’s als een soort “silo’s” aangesloten? Of is het mogelijk om te zoeken over instellingen heen? Hoe werkt dat?

De totale keten wordt momenteel door SURF ontworpen: van aangesloten API's, via OOAPI-gateway, tot de onderwijsexplorer pilot. De aangesloten API endpoints zijn inderdaad silo's. De OOAPI-gateway zorgt ervoor dat data uit verschillende silo's opgevraagd kan worden. Zoeken is onderdeel van de OOAPI specificatie, daarmee kan per silo gezocht worden. Over instellingen heen moet de OOAPI-gateway of de Onderwijsexplorer iets aanvullends doen. Het is de onderwijsexplorer die zijn specifieke zoek wensen zelf gaat implementeren.

Voor generieke instellingsoverstijgende informatie zetten we de OOAPI-gateway in. Dit is bijvoorbeeld het geval bij de vraag: welke instellingen (lees aangesloten API's) zijn te gebruiken door de onderwijsexplorer.

6. In de stimuleringsregeling wordt gesproken over het bijwonen van 2 hackatons. Wat wordt er van dit bijwonen verwacht? Is het om hackaton-teams daar te voorzien van antwoorden wat we vanuit het onderwijsveld graag zouden zien?

Je kunt de hackatons het beste zien als een moment om je eigen vragen beantwoord te krijgen, je eigen vorderingen te laten zien en jouw data zichtbaar te krijgen via de OOAPI-gateway. Het is een moment waarop alle deelnemers bij elkaar komen om van elkaar te leren, de code op elkaar aan te laten sluiten en de hele keten te toetsen. Je bent dus zelf het hackaton team wat deels zijn voortgang met anderen deelt en anderzijds handson kan werken aan de eigen code. Let wel deelname aan de hackathons 25 februari en 20 april door tenminste de betrokken software-ontwikkelaars en de projectleiders een verplichting is, zoals gesteld is in de Stimuleringsregeling. De hackathon op 20 april gebruiken we om de hele keten (OOAPI endpoint, Gateway, onderwijsexplorer) op elkaar aan te sluiten en werkend te krijgen. Een functionerend OOAPI endpoint aan de kant van de instelling is dus op 20 april nodig.

7. Daarnaast staat er dat alle software die ontwikkeld wordt in het kader van deze stimuleringregeling onder een open-source licentie beschikbaar gesteld moet worden. Hoe ruim moet ik dat interpreteren? In ons geval zijn wel al bezig met een app en de koppeling middels een integratie-platform. Welke delen moeten dan open source worden?

Zie FAQ 4.

8. Hoe gaat de OOAPI om met meertaligheid?

De instelling die een endpoint implementeert bepaalt zelf welke taal de responses zijn en dat kan dus tussen instellingen verschillen. Er een openstaand issue om in de nabije toekomst iets in de specificatie op te nemen over meertaligheid. Er is consensus bereikt om dit met http content negotiation te implementeren, zie https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language. De frontend zal dan proberen via de header "Accept-Language: nl" content op te vragen en de resultaten weergeven ongeacht in welke taal die terugkomt.

9. Hoe gaat de OOAPI om met informatie in verschillende studiejaren?

Informatie (van programs, courses en components) wordt aangeboden in de offerings. Er zijn dus programOfferings, courseOfferings en componentOfferings. Offerings vallen in een bepaalde academicSession. Een academicSession kan een studiejaar zijn, of een semester, trimester, blok of andere periode. Waarbij een bepaalde periode ook een verwijzing heeft naar het academisch jaar in het attribuut academicSession.year.

Daarnaast heeft iedere offering nog een eigen startDate en endDate. Waarin de preciese start- en einddatum van de offering aangegeven kan worden. Dat kan bijvoorbeeld week 3 zijn van een bepaald blok.

10. Hoe gaan we om met HATEAOS (Hypermedia As The Engine Of Application State) en de _links?

In v4 van de OOAPI is het principe van HATEAOS losgelaten.

11. Is de OOAPI ook geschikt als een mechanisme voor system-system uitwisseling?

De OOAPI is oorspronkelijk ontworpen als system-client interface. De objecten en attributen zoals die in de OOAPI specificatie beschreven staan, kunnen wel helpen bij het nadenken over system-system interfaces. Een andere inspiratiebron zou bijv. LIS OneRoster kunnen zijn. In de stimuleringsregeling blijven we gewoon gebruik maken van de OOAPI specificatie as is. Wel denkt SURF na over mogelijke toekomstige uitbreidingen op de OOAPI om system-to-system uitwisselingen beter te faciliteren.

12. Is de OOAPI gateway een system (en dus onderdeel van een system-system interface)?

Nee, de OOAPI gateway is (zoveel mogelijk) transparant en handelt uit naam van de client.

13. Hoe ga ik om met eigen attributen, die niet in de specificatie voorkomen, maar wel noodzakelijk zijn voor eigen applicaties?

In iedere response van een OOAPI object is een 'ext' object gedefinieerd in dit object kun je eigen attributen opnemen.

14. Hoe moet het crohoCreboCode attribuut van eenprogram ingevuld worden?

Voor de frontend is dit veld van groot belang, want met dit veld sorteren we de opleidingen en kan er door studenten makkelijker gezocht worden naar opleidingen en vakken. Het is de bedoeling om de crohoCode in te vullen in het geval van een HO instelling en de creboCode in het geval van een MBO instelling. Wij zullen de code, bijvoorbeeld 59312, herleiden naar één van de volgende sectoren.

  • Economie
  • Gezondheidszorg
  • Gedrag & Maatschappij
  • Landbouw & Natuurlijke omgeving
  • Natuur
  • Onderwijs
  • Taal & Cultuur
  • Recht
  • Techniek
  • Sectoroverstijgend

Elk program hoort dus thuis in één van deze sectoren. Op basis van de CROHO opleidingscode van de opleiding is te achterhalen in welke sector deze thuishoort. Zie ook: https://www.onderwijsinspectie.nl/onderwijssectoren/hoger-onderwijs/sectoren/indeling-sectoren.

15. Hoe wordt het verkeer tussen een instellings-endpoint en de gateway beveiligd?

  • Al het http verkeer dient in ieder geval beveiligd te zijn met SSL: https.
  • Tijdens deze stimuleringsregeling kun je verder kiezen tussen:
    • HTTP Basic authentication (username / password)
    • Oauth2 client credentials (key)
  • Indien gewenst kun je het endpoint afschermen met een firewall. De reeks 145.100.189.160/27 dient dan gewhitelist te zijn voor verkeer op poort 443.

16. Hoe snel moet een instellings-endpoint een response teruggeven?

We hebben afgesproken dat een endpoint binnen 2500ms een respons moet teruggeven.

17. Mogen beschrijvingsvelden (description attributen) html tags bevatten?

De OOAPI specificatie doet hier geen uitspraken over, in de OOAPI werkgroep overleg is er wel gesproken om 'markdown' te accepteren in 'beschrijvings' attributen.

18. Hoe interpreteren we het datamodel ook alweer?

Het datamodel wordt hier benoemd: Datamodel v4 & Endpoints. De belangrijkste inzichten zijn:

  • OOAPI sluit aan op de principes van IMS EduAPI. Dat betekent dat we de objecten beschrijven in een 9-vlaks model
    • Er zijn 3 objecten
      1. programs, dit zijn opleidingen, minor of andere verzamelingen van vakken.
      2. courses, dit zijn vakken.
      3. components, dit zijn onderdelen van een vak, zoals een hoorcollege of toets.
    • Die 3 objecten hebben 3 eigenschappen
      1. De objecten worden beschreven in program, course & component. Voor bijvoorbeeld gebruik in een onderwijscatalogus.
      2. De objecten worden op een bepaald moment in tijd aangeboden, dat heet een offering. Er zijn dus programOfferings, courseOfferings en componentOfferings.
      3. Aan deze offerings kunnen personen zich verbinden, dat noemen we associations. Door bijvoorbeeld student inschrijvingen op een vak, of coordinatoren van een opleiding te registreren. Er zijn dus ook programOfferingAssociations, courseOfferingAssociations en componentOfferingAssociations.
  • Programs, courses en components zijn onderdeel van een organizations object. Dit organizations object kan gebruikt worden om de instituten, faculteiten en/of domeinen van de instelling te benoemen.
  • Offerings worden aangeboden op een bepaald moment in tijd en in een bepaald academisch jaar. Die verschillende perioden kunnen worden opgenomen in het object: academicSessions.
  • Het eventuele resultaat wat een persoon behaald op een offering waarmee hij geassocieerd is, is onderdeel van de association zelf. De personen worden in een apart persons object beschreven.

19. Zijn query parameters, zoals q, pageNumber en sort hoofdletter gevoelig?

Nee, in url's hebben hoofd- en kleine letters geen betekenis. pageNumber & pagenumber en PAGENUMBER matchen dus allemaal op het veld pageNumber.

20. Hoe lang blijft de infrastructuur die SURF heeft ontwikkeld (de OOAPI Gataway en de demonstrator frontend) online?

Aangezien het in dit project gaat om een pilot kan de infrastructuur nog veranderen als de stimuleringsregeling afgerond is. De infrastructuur zal na de pilot tot 31-12-2021 beschikbaar blijven in een bepaalde vorm. SURF werkt toe naar dienstverlening rondom de OOAPI-gateway, waardoor continuïteit gewaarborgd blijft. De precieze invulling en de haalbaarheid van deze dienst wordt in de komende periode bepaald.

21. Welk type associations zijn nodig voor het aanbieden van onderwijsaanbod?

Voor onderwijsaanbod is het goed de 'lecturer' en 'coordinator' rol te ontwikkelen. Om te orienteren op een vak kan het van toegevoegde waarde zijn om te weten wie het vak doceert. Daarnaast kan de coordinator gebruikt worden als contactpersoon voor specifieke vragen over een vak. Het is niet nodig de 'student' rol aan te bieden. Het is niet nodig te weten wie al voor een vak ingetekend heeft.

22a. Als een instelling ervoor kiest om de leerdoelen als tekstbox (HTML) te definiëren is het dan de bedoeling dat hiervoor 1 string-object wordt aangeleverd, of wordt dit dan een omschrijving?

22b. Waarom is leerdoelen een string[] en geen object? Ik zou verwachten dat je zowel leerdoel als niveau waarop het leerdoel wordt geleverd wil weten.

We gaan er bij het beantwoorden van deze vragen (22a en 22b) vanuit dat het over vakken gaat, dus dat dit /courses/{courseId}.learningOutcomes betreft.

Het klopt dat learningOutcomes een array van strings is. Een lijst van één of meerdere learningOutcomes dus. Het niveau van het vak kan opgegeven worden in /courses/{courseId}.level. Er is dus één niveau dat voor alle learningOutcomes geldt. Wat we zien is dat er bij veel instellingen voor een vak vaak een aantal outcomes beschreven staan als een lijstje met punten, vandaar de array. Mocht er voor een vak maar één outcome beschreven staan dan kan die als het eerste en enige element in de array doorgegeven worden.

Als de instelling learningOutcomes gebruikt om het vak te beschrijven, dan is het inderdaad een optie om die in de de /courses/{courseId}.description op te nemen. Let wel op dat daar dan geen HTML in kan zitten. Wel kan er gebruik gemaakt worden van markdown.

23. Is er een lijstje met de omschrijvingen die verwacht worden van een specifieke course, of zijn alleen description, requirements, enrollment en assessment gewenst?

De required velden van OOAPI zijn aangegeven in de specificatie. Dat zijn voor het object /courses/{courseId}:

  • courseId
  • name
  • abbreviation
  • description
  • level

Verder wordt er niets verwacht. Hoe meer info hoe beter, want dan kunnen verschillende frontends van de data gebruik maken. De demo omgeving zal aangeven welke velden wel en welke velden niet gebruikt worden. 

Als je als voorbeeld van een frontend naar eduXchange kijkt. Dat is een omgeving voor het intekenen op bijvakken. Dan worden de volgende aanvullende velden gebruikt:

  • learningOutcomes
  • requirements
  • enrollment
  • ects
  • coordinator

Ook worden van de aanbiedingen van cursussen nog gegevens gebruikt. Dat betreft van /courses/{courseId}/offerings de volgende attributen:

  • mainLanguage
  • academicSession
  • maNumberOfStudents en enrolledNumberOfStudents
  • startDate & endDate

24. Hoe heeft CACI vorig jaar het OOAPI v3 endpoint geïmplementeerd in Osiris?

Hier is documentatie over beschikbaar, een samenvatting daarvan is hier te vinden: Samenvatting documentatie Osiris 2019

25. Hoe moet je omgaan met niet-verplichte attributen die je niet kunt aanleveren?

In dat geval laat je het attribuut weg. Dus zo (vergelijk het attribuut ects):

good
{   
    "courseId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Academic and Professional Writing",
    "abbreviation": "INFOMQNM",
    "description": "As with all empirical sciences, to assure valid outcomes, HCI studies heavily rely on research methods and statistics.",
    "level": "master"
}

En niet zo:

bad
{   
    "courseId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Academic and Professional Writing",
    "abbreviation": "INFOMQNM",
    "ects": null,
    "description": "As with all empirical sciences, to assure valid outcomes, HCI studies heavily rely on research methods and statistics.",
    "level": "master"
}




  • No labels