OSR:2019/Opvragen informatie over onderwijsinstelling

Inleiding

Men kan informatie over onderwijsinstellingen opvragen met behulp van deze operatie. De aanwezige stamgegevens zijn afkomstig van DUO Open onderwijsdata.

Informatie over een onderwijsinstelling (BRIN4) opvragen

Onderstaand staat beschreven hoe informatie over alle onderwijsinstellingen op te vragen.

Aanroep

API endpoint

GET

/schools

Voorbeeld

Het is mogelijk om specifiek te zoeken met een combinatie van verschillende parameters, welke met een AND-operator ("&") gecombineerd kunnen worden.

/schools?name=Vakschool&oin=0000000700000EF00000&brin=00EF&oa_id=123A125

Parameters	Omschrijving	Verplicht/Optioneel
Name	Naam van de onderwijsinstelling.	Optioneel
oin	OIN van de onderwijsinstelling.	Optioneel
brin	BRIN4 van de onderwijsinstelling.	Optioneel
oa_id	Onderwijs aanbieder id van de onderwijsinstelling (momenteel niet gevuld).	Optioneel

Response

Voorbeeld

De response kan uit 0, 1 of meerdere onderwijsinstellingen bestaan.

[
      {
      "name": "GBS De Morgenster",
      "oin": "0000000700000AV00000",
      "brin": "00AV",
      "oa_id": "123A123",
      "_links":       {
         "self": {"href": "/api/v2/schools/1"},
         "board": {"href": "/api/v2/boards/1"}
      }
   },
      {
      "name": "Scholengemeenschap voor Voortgezet Vrije Schoolonderwijs",
      "oin": "0000000700000CB00000",
      "brin": "00CB",
      "oa_id": "123A124",
      "_links":       {
         "self": {"href": "/api/v2/schools/2"},
         "board": {"href": "/api/v2/boards/2"}
      }
   }
]

Veld	Omschrijving
Name	Naam van de onderwijsinstelling.
oin	OIN van de onderwijsinstelling.
brin	BRIN4 van de onderwijsinstelling.
oa_id	Onderwijs aanbieder id van de onderwijsinstelling (momenteel niet gevuld).
_link self	Directe link naar informatie van deze onderwijsinstelling. Het id is het id van de onderwijsinstelling in het OSR.
_link board	Directe link naar informatie over het bestuur van deze onderwijsinstelling. Het id is het id van het bestuur in het OSR.

Codes

Route	Code	Inhoud
schools	200	Lijst met schoolobjecten of lege lijst (indien er geen match gevonden is).
schools/{id}	200	Één schoolobject, behorende bij het {id}.
schools/{id}	404	Melding: "School with id {id} does not exist".

Informatie over een bestuur opvragen

Informatie over een bestuur kan worden opgevraagd door de direct link naar board binnen de response van GET /schools te gebruiken:

Aanroep

API endpoint

GET	/api/v2/boards/{id}

Response

Voorbeeld

{ 
   "number": "41646", 
   "name": "GPO-WN", 
   "_links":    { 
      "self": {"href": "/api/v2/boards/1"}, 
      "schools":       [ 
         {"href": "/api/v2/schools/1"}, 
         {"href": "/api/v2/schools/16"}, 
         {"href": "/api/v2/schools/17"} 
      ] 
   } 
}

Veld	Omschrijving
number	Bestuursnummer.
name	Naam van het bestuur.
_links self	Directe link naar informatie over het bestuur. Id is een intern id van het OSR.
_links schools	Er kunnen 1 of meerdere scholen onder een bestuur vallen. In dit voorbeeld wordt een lijst teruggegeven van scholen met een direct link naar informatie over de desbetreffende onderwijsinstelling(en).

Codes

Route	Code	Inhoud response
boards/{id}	200	Één bestuursobject, behorende bij het {id}
boards/{id}	404	Melding: "Board with id {id} does not exist"

Voor wie?

Deze service is beschikbaar voor iedereen.
Voor TLS verbindingen (minimaal TLS 1.2) moet een aanvragende partij een geldige PKI overheidscertifcaat/ODOC certificaat gebruiken
Zie meer informatie over de API op https://osr.kennisnet.nl/api/v2/documentation

Over het gebruik van certificaten

Let op: Bij nieuw aan te vragen certificaten wordt sterk aangeraden te kiezen voor een PKI-overheidscertificaat. Dit omdat ODOC-certificaten geen onderdeel meer uitmaken van de aankomende Edukoppeling Transactiestandaard versie 1.3.