Brontekst bekijken van 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.<br>


==Opvragen informatie onderwijsinstelling==
Onderstaande request is het basisrequest om alle onderwijsinstellingen op te vragen.

GET Request<br>

<syntaxhighlight lang="json">
/api/v1/schools
</syntaxhighlight>

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

<syntaxhighlight lang="json">
/api/v1/schools?name=Vakschool&oin=0000000700000EF00000&brin=00EF&oa_id=123A125
</syntaxhighlight>

{|class="wikitable"
! style="text-align:left;"| Parameters
! style="text-align:left;"| Omschrijving
! style="text-align:left;"| Verplicht/Optioneel
! 
|-
| | Name
| Naam van de onderwijsinstelling.
| | Optioneel
|-
| | oin
| Oin van de onderwijsinstelling
| | Optioneel
|-
| | brin
| Brin van de onderwijsinstelling
| | Optioneel
|-
| | oa_id
| Onderwijs aanbieder id van de onderwijsinstelling. Dit komt uit RIO
| | Optioneel
|}


Foutcodes

{|class="wikitable"
! style="text-align:left;"| Route
! style="text-align:left;"| Code
! style="text-align:left;"| Melding
|-
| | schools/{id}
| | 200
| | school object
}

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

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

</syntaxhighlight>

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

{|class="wikitable"
! style="text-align:left;"| Parameters
! style="text-align:left;"| Omschrijving
! 
|-
| | Name
| Naam van de onderwijsinstelling.
|-
| | oin
| Oin van de onderwijsinstelling
|-
| | brin
| Brin van de onderwijsinstelling
|-
| | oa_id
| Onderwijs aanbieder id van de onderwijsinstelling. Dit komt uit RIO
|-
| | _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
|}

==Directe link naar board==
Informatie over het bestuur kan worden opgevraagd door de direct link naar board te gebruiken:

GET Request

<syntaxhighlight lang="json">
/api/v1/boards/3
</syntaxhighlight>

Hieronder is een voorbeeld weergegeven van de response:<br>

<syntaxhighlight lang="json">
{ 
   "number": "41646", 
   "name": "GPO-WN", 
   "_links":    { 
      "self": {"href": "/api/v1/boards/1"}, 
      "schools":       [ 
         {"href": "/api/v1/schools/1"}, 
         {"href": "/api/v1/schools/16"}, 
         {"href": "/api/v1/schools/17"} 
      ] 
   } 
}

</syntaxhighlight>

{|class="wikitable"
! style="text-align:left;"| Parameter
! style="text-align:left;"| 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. <br> In dit voorbeeld wordt een array teruggegeven van scholen. Direct link naar informatie over de desbetreffende onderwijsinstelling
|}

==Voor wie?==
Deze service is beschikbaar voor iedereen.<br>
Voor TLS verbindingen (minimaal TLS 1.2) moet een aanvragende partij een geldige PKI overheidscertifcaat/ODOC certificaat gebruiken<br>
Zie meer informatie over de API op https://osr-api-sb.kennisnet.nl/api/v1/doc<br>

==Validaties==

Het VO-koppelpunt hanteert de volgende validaties voor binnenkomende berichten.

{| cellspacing="5" cellpadding="0" style="margin:0em 0em 1em 0em; border:1px solid #1DA0E7; background:#fffdc4;width:100%"
| ''' Let op:'''<br>Bij nieuw aan te vragen certificaten wordt sterk aangeraden te kiezen voor een PKI-overheidscertificaat.<br>Dit omdat ODOC-certificaten geen onderdeel meer uitmaken van de aankomende Edukoppeling Transactiestandaard versie 1.3.
|}