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

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken
(Response)
(Directe link naar board)
Regel 171: Regel 171:
 
| | _links schools
 
| | _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
 
| 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
 +
|}
 +
 +
 +
Foutcodes
 +
 +
{|class="wikitable"
 +
! style="text-align:left;"| Route
 +
! style="text-align:left;"| Code
 +
! style="text-align:left;"| Melding
 +
|-
 +
| | boards/{id}
 +
| | 200
 +
| | board object
 +
|
 +
| | boards/{id}
 +
| | 404
 +
| | board with {id} does not exist
 
|}
 
|}
  

Versie van 20 mrt 2019 om 15:27

Inleiding

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


Opvragen informatie onderwijsinstelling

Onderstaande request is het basisrequest om alle onderwijsinstellingen op te vragen.

GET Request

/api/v1/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/v1/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 Brin van de onderwijsinstelling Optioneel
oa_id Onderwijs aanbieder id van de onderwijsinstelling. Dit komt uit RIO Optioneel


Foutcodes

Route Code Melding
schools/{id} 200 school object
schools/{id} 404 school with {id} does not exist

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

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

Foutcodes

Route Code Melding
schools 200 array met scholen of lege array

Directe link naar board

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

GET Request

/api/v1/boards/3

Hieronder is een voorbeeld weergegeven van de response:

{ 
   "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"} 
      ] 
   } 
}
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 array teruggegeven van scholen. Direct link naar informatie over de desbetreffende onderwijsinstelling


Foutcodes

Route Code Melding
boards/{id} 200 board object boards/{id} 404 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-api-sb.kennisnet.nl/api/v1/doc

Validaties

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

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.