OSR:2019/Opvragen informatie over onderwijsinstelling: verschil tussen versies

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken
k (Voorbeeld)
k (Voorbeeld)
Regel 75: Regel 75:
   
 
</syntaxhighlight>
 
</syntaxhighlight>
 
Als de lijst met onderwijsinstellingen leeg is (er is geen match gevonden) wordt er "HTTP/1.1 200 OK" geretourneerd.
 
   
 
{|class="wikitable"
 
{|class="wikitable"

Versie van 30 jul 2021 om 13:25

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

Codes

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:

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 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

Info.gif 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.