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

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken
k (Opvragen informatie onderwijsinstelling)
k (Reponse)
 
(34 tussenliggende versies door 2 gebruikers niet weergegeven)
Regel 4: Regel 4:
  
  
==Opvragen informatie onderwijsinstelling==
+
==Informatie over een onderwijsinstelling opvragen==
Onderstaande request is het basisrequest om alle onderwijsinstellingen op te vragen.
 
  
GET Request<br>
+
===Request===
 +
Onderstaand staat beschreven hoe informatie over alle onderwijsinstellingen op te vragen.
  
<syntaxhighlight lang="json">
+
<table><tr>
/api/v2/schools
+
<td><span style="color:white;font-weight:bold;background-color:#61affe;padding:6px 15px">GET</span></td>
</syntaxhighlight>
+
<td><syntaxhighlight lang="json" style="display:inline";> /api/v2/schools</syntaxhighlight></td>
 +
</tr></table>
  
 
Het is mogelijk om specifiek te zoeken, onderstaande geeft een voorbeeld weer van de verschillende parameters.<br>
 
Het is mogelijk om specifiek te zoeken, onderstaande geeft een voorbeeld weer van de verschillende parameters.<br>
Regel 24: Regel 25:
 
! style="text-align:left;"| Omschrijving
 
! style="text-align:left;"| Omschrijving
 
! style="text-align:left;"| Verplicht/Optioneel
 
! style="text-align:left;"| Verplicht/Optioneel
!
 
 
|-
 
|-
 
| | Name
 
| | Name
Regel 35: Regel 35:
 
|-
 
|-
 
| | brin
 
| | brin
| Brin van de onderwijsinstelling
+
| BRIN4 van de onderwijsinstelling
 
| | Optioneel
 
| | Optioneel
 
|-
 
|-
 
| | oa_id
 
| | oa_id
| Onderwijs aanbieder id van de onderwijsinstelling. Dit komt uit RIO
+
| Onderwijs aanbieder id van de onderwijsinstelling (momenteel niet gevuld).
 
| | Optioneel
 
| | Optioneel
 
|}
 
|}
  
 
+
===Response===
Responsecodes
 
 
 
{|class="wikitable"
 
! style="text-align:left;"| Route
 
! style="text-align:left;"| Code
 
! style="text-align:left;"| 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:<br>
 
De response kan uit 0, 1 of meerdere onderwijsinstellingen bestaan. Hieronder is een voorbeeld weergegeven van de response:<br>
  
Regel 95: Regel 78:
 
! style="text-align:left;"| Parameters
 
! style="text-align:left;"| Parameters
 
! style="text-align:left;"| Omschrijving
 
! style="text-align:left;"| Omschrijving
!
 
 
|-
 
|-
 
| | Name
 
| | Name
Regel 101: Regel 83:
 
|-
 
|-
 
| | oin
 
| | oin
| Oin van de onderwijsinstelling
+
| OIN van de onderwijsinstelling
 
|-
 
|-
 
| | brin
 
| | brin
| Brin van de onderwijsinstelling
+
| BRIN4 van de onderwijsinstelling
 
|-
 
|-
 
| | oa_id
 
| | oa_id
| Onderwijs aanbieder id van de onderwijsinstelling. Dit komt uit RIO
+
| Onderwijs aanbieder id van de onderwijsinstelling (momenteel niet gevuld).
 
|-
 
|-
 
| | _link self
 
| | _link self
Regel 116: Regel 98:
 
|}
 
|}
  
Foutcodes
+
 
 +
Responsecodes
  
 
{|class="wikitable"
 
{|class="wikitable"
Regel 125: Regel 108:
 
| | schools
 
| | schools
 
| | 200
 
| | 200
| | array met scholen of lege array
+
| | Lijst met schoolobjecten of lege lijst
 +
|-
 +
| | schools/{id}
 +
| | 200
 +
| | schoolobject
 +
|-
 +
| | schools/{id}
 +
| | 404
 +
| | Melding: school with {id} does not exist
 
|}
 
|}
  
==Directe link naar board==
+
==Informatie over een bestuur opvragen==
Informatie over het bestuur kan worden opgevraagd door de direct link naar board te gebruiken:
+
Informatie over een bestuur kan worden opgevraagd door de direct link naar board binnen de response van GET /schools te gebruiken:
 
+
===Request===
GET Request
+
<table><tr>
 +
<td><span style="color:white;font-weight:bold;background-color:#61affe;padding:6px 15px">GET</span></td>
 +
<td><syntaxhighlight lang="json" style="display:inline";> /api/v2/boards/{id}</syntaxhighlight></td>
 +
</tr></table>
  
<syntaxhighlight lang="json">
 
/api/v2/boards/3
 
</syntaxhighlight>
 
  
 
Hieronder is een voorbeeld weergegeven van de response:<br>
 
Hieronder is een voorbeeld weergegeven van de response:<br>
Regel 158: Regel 149:
 
! style="text-align:left;"| Parameter
 
! style="text-align:left;"| Parameter
 
! style="text-align:left;"| Omschrijving
 
! style="text-align:left;"| Omschrijving
!
 
 
|-
 
|-
 
| | number
 
| | number
Regel 170: Regel 160:
 
|-
 
|-
 
| | _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 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:<br>
 +
 +
<syntaxhighlight lang="json">
 +
{
 +
  "number": "012345",
 +
  "name": "Voorbeeldbestuur",
 +
  "_links": {
 +
    "self": {
 +
      "href": "/api/v2/boards/1"
 +
    }
 +
  }
 +
}
 +
 +
</syntaxhighlight>
  
 
Foutcodes
 
Foutcodes
Regel 187: Regel 193:
 
| | boards/{id}
 
| | boards/{id}
 
| | 404
 
| | 404
| | board with {id} does not exist
+
| | Melding: board with {id} does not exist
 
|}
 
|}
  
Regel 193: Regel 199:
 
Deze service is beschikbaar voor iedereen.<br>
 
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>
 
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-sb.kennisnet.nl/api/v2/documentation<br>
+
Zie meer informatie over de API op https://osr.kennisnet.nl/api/v2/documentation<br>
 
 
==Validaties==
 
  
Het VO-koppelpunt hanteert de volgende validaties voor binnenkomende berichten.
+
==Over het gebruik van certificaten==
  
 
{{Info|''' 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.}}
 
{{Info|''' 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.}}
  
 
[[Category:OSR]]
 
[[Category:OSR]]

Huidige versie van 30 okt 2020 om 16:31

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

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.