OSR:2019/Opvragen informatie over onderwijsinstelling

Inleiding

Men kan informatie over onderwijsinstellingen opvragen met behulp van deze operatie. De aanwezige data is afkomstig van DUO Open data / RIO.

Informatie over een onderwijsinstelling opvragen

Request

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

GET	/api/v2/schools

Het is mogelijk om specifiek te zoeken, onderstaande geeft een voorbeeld weer van de verschillende parameters.
Let op, de parameters worden met een ‘AND’ operator gecombineerd.

/api/v2/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

De response kan uit 0, 1 of meerdere onderwijsinstellingen bestaan. Hieronder is een voorbeeld weergegeven van de response:

[
      {
      "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"}
      }
   }
]

De Lijst kan leeg zijn als er geen match is gevonden. HTTP/1.1 200 OK wordt geretourneerd

Parameters	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. Id is een interne ID van het OSR
_link board	Directe link naar informatie van het board van deze onderwijsinstelling. Id is een interne ID van het OSR

Responsecodes

Route	Code	Melding
schools	200	Lijst met schoolobjecten of lege lijst
schools/{id}	200	schoolobject
schools/{id}	404	Melding: school with {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:

Request

GET	/api/v2/boards/{id}

Hieronder is een voorbeeld weergegeven van de response:

{ 
   "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"} 
      ] 
   } 
}

Parameter	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).

Reponse

De response kan uit een board-object of foutmelding bestaan. Hieronder is een voorbeeld weergegeven van de response:

{
  "number": "012345",
  "name": "Voorbeeldbestuur",
  "_links": {
    "self": {
      "href": "/api/v2/boards/1"
    }
  }
}

Foutcodes

Route	Code	Melding
boards/{id}	200	board object
boards/{id}	404	Melding: board with {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.