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

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken
(Opvragen informatie onderwijsinstelling)
k (Codes)
 
(81 tussenliggende versies door 3 gebruikers niet weergegeven)
Regel 1: Regel 1:
   
 
==Inleiding==
 
==Inleiding==
Men kan informatie over onderwijsinstellingen opvragen met behulp van deze operatie. De aanwezige data is afkomstig van DUO Open data / RIO.<br>
+
Men kan informatie over onderwijsinstellingen opvragen met behulp van deze operatie. De aanwezige stamgegevens zijn afkomstig van DUO Open onderwijsdata.<br>
   
  +
==Informatie over een onderwijsinstelling (BRIN4) opvragen==
   
==Opvragen informatie onderwijsinstelling==
 
Onderstaande request is het basisrequest om alle onderwijsinstellingen op te vragen.
 
   
  +
Onderstaand staat beschreven hoe informatie over alle onderwijsinstellingen op te vragen.
GET Request<br>
 
   
  +
===Aanroep===
<syntaxhighlight lang="json">
 
  +
====API endpoint====
/api/v1/schools
 
  +
<table><tr>
</syntaxhighlight>
 
  +
<td><span style="color:white;font-weight:bold;background-color:#61affe;padding:6px 15px">GET</span></td>
  +
<td><syntaxhighlight lang="json" style="display:inline";> /schools</syntaxhighlight></td>
  +
</tr></table>
  +
  +
====Voorbeeld====
   
Het is mogelijk om specifiek te zoeken, onderstaande geeft een voorbeeld weer van de verschillende parameters.<br>
+
Het is mogelijk om specifiek te zoeken met een combinatie van verschillende parameters, welke met een AND-operator ("&") gecombineerd kunnen worden.<br>
Let op, de parameters worden met een ‘AND’ operator gecombineerd.<br>
 
   
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
/api/v1/schools?name=Vakschool&oin=0000000700000EF00000&brin=00EF&oa_id=123A125
+
/schools?name=Vakschool&oin=0000000700000EF00000&brin=00EF&oa_id=123A125
 
</syntaxhighlight>
 
</syntaxhighlight>
   
Regel 24: Regel 27:
 
! 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 31: Regel 33:
 
|-
 
|-
 
| | oin
 
| | oin
| Oin van de onderwijsinstelling
+
| OIN van de onderwijsinstelling.
 
| | Optioneel
 
| | Optioneel
 
|-
 
|-
 
| | 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===
   
  +
====Voorbeeld====
Foutcodes
 
  +
De response kan uit 0, 1 of meerdere onderwijsinstellingen bestaan.
 
{|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">
 
<syntaxhighlight lang="json">
Regel 67: Regel 58:
 
"oa_id": "123A123",
 
"oa_id": "123A123",
 
"_links": {
 
"_links": {
"self": {"href": "/api/v1/schools/1"},
+
"self": {"href": "/api/v2/schools/1"},
"board": {"href": "/api/v1/boards/1"}
+
"board": {"href": "/api/v2/boards/1"}
 
}
 
}
 
},
 
},
Regel 77: Regel 68:
 
"oa_id": "123A124",
 
"oa_id": "123A124",
 
"_links": {
 
"_links": {
"self": {"href": "/api/v1/schools/2"},
+
"self": {"href": "/api/v2/schools/2"},
"board": {"href": "/api/v1/boards/2"}
+
"board": {"href": "/api/v2/boards/2"}
 
}
 
}
 
}
 
}
Regel 84: Regel 75:
   
 
</syntaxhighlight>
 
</syntaxhighlight>
 
De Lijst kan leeg zijn als er geen match is gevonden.
 
HTTP/1.1 200 OK wordt geretourneerd
 
   
 
{|class="wikitable"
 
{|class="wikitable"
! style="text-align:left;"| Parameters
+
! style="text-align:left;"| Veld
 
! style="text-align:left;"| Omschrijving
 
! style="text-align:left;"| Omschrijving
!
 
 
|-
 
|-
 
| | Name
 
| | Name
Regel 97: Regel 84:
 
|-
 
|-
 
| | 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
| Directe link naar informatie van deze onderwijsinstelling. Id is een interne ID van het OSR
+
| Directe link naar informatie van deze onderwijsinstelling. Het id is het id van de onderwijsinstelling in het OSR.
 
|-
 
|-
 
| | _link board
 
| | _link board
| Directe link naar informatie van het board van deze onderwijsinstelling. Id is een interne ID van het OSR
+
| Directe link naar informatie over het bestuur van deze onderwijsinstelling. Het id is het id van het bestuur in het OSR.
 
|}
 
|}
   
  +
====Codes====
==Directe link naar board==
 
Informatie over het bestuur kan worden opgevraagd door de direct link naar board te gebruiken:
 
   
  +
{|class="wikitable"
GET Request
 
  +
! style="text-align:left;"| Route
  +
! style="text-align:left;"| Code
  +
! style="text-align:left;"| Inhoud
  +
|-
  +
| | schools
  +
| | 200
  +
| | Lijst met schoolobjecten of lege lijst (indien er geen match gevonden is).
  +
|-
  +
| | schools/{id}
  +
| | 200
  +
| | Één schoolobject, behorende bij het {id}.
  +
|-
  +
| | schools/{id}
  +
| | 404
  +
| | Melding: "School with id {id} does not exist".
  +
|}
   
  +
==Informatie over een bestuur opvragen==
<syntaxhighlight lang="json">
 
  +
Informatie over een bestuur kan worden opgevraagd door de direct link binnen de response van GET /schools te gebruiken:
/api/v1/boards/3
 
  +
===Aanroep===
</syntaxhighlight>
 
  +
  +
====API endpoint====
  +
<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>
   
Hieronder is een voorbeeld weergegeven van de response:<br>
 
   
  +
===Response===
  +
====Voorbeeld====
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
 
{
 
{
Regel 128: Regel 137:
 
"name": "GPO-WN",
 
"name": "GPO-WN",
 
"_links": {
 
"_links": {
"self": {"href": "/api/v1/boards/1"},
+
"self": {"href": "/api/v2/boards/1"},
 
"schools": [
 
"schools": [
{"href": "/api/v1/schools/1"},
+
{"href": "/api/v2/schools/1"},
{"href": "/api/v1/schools/16"},
+
{"href": "/api/v2/schools/16"},
{"href": "/api/v1/schools/17"}
+
{"href": "/api/v2/schools/17"}
 
]
 
]
 
}
 
}
Regel 140: Regel 149:
   
 
{|class="wikitable"
 
{|class="wikitable"
! style="text-align:left;"| Parameter
+
! style="text-align:left;"| Veld
 
! style="text-align:left;"| Omschrijving
 
! style="text-align:left;"| Omschrijving
!
 
 
|-
 
|-
 
| | number
 
| | number
| Bestuursnummer
+
| Bestuursnummer.
 
|-
 
|-
 
| | name
 
| | name
| Naam van het bestuur
+
| Naam van het bestuur.
 
|-
 
|-
 
| | _links self
 
| | _links self
| Directe link naar informatie over het bestuur. Id is een intern ID van het OSR
+
| Directe link naar informatie over het bestuur. Het id is het id van het bestuur in het OSR.
 
|-
 
|-
 
| | _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).
  +
|}
  +
  +
====Codes====
  +
  +
{|class="wikitable"
  +
! style="text-align:left;"| Route
  +
! style="text-align:left;"| Code
  +
! style="text-align:left;"| Inhoud response
  +
|-
  +
| | boards/{id}
  +
| | 200
  +
| | Één bestuursobject, behorende bij het {id}.
  +
|-
  +
| | boards/{id}
  +
| | 404
  +
| | Melding: "Board with id {id} does not exist".
 
|}
 
|}
   
Regel 160: Regel 184:
 
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-api-sb.kennisnet.nl/api/v1/doc<br>
+
Zie meer informatie over de API op https://osr.kennisnet.nl/api/v2/documentation<br>
   
  +
==Over het gebruik van certificaten==
==Validaties==
 
   
  +
{{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.}}
Het VO-koppelpunt hanteert de volgende validaties voor binnenkomende berichten.
 
   
  +
[[Category:OSR]]
{| 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.
 
|}
 

Huidige versie van 30 jul 2021 om 13:36

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. Het id is het id van de onderwijsinstelling in het OSR.
_link board Directe link naar informatie over het bestuur van deze onderwijsinstelling. Het id is het id van het bestuur in het OSR.

Codes

Route Code Inhoud
schools 200 Lijst met schoolobjecten of lege lijst (indien er geen match gevonden is).
schools/{id} 200 Één schoolobject, behorende bij het {id}.
schools/{id} 404 Melding: "School with id {id} does not exist".

Informatie over een bestuur opvragen

Informatie over een bestuur kan worden opgevraagd door de direct link 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. Het id is het id van het bestuur in 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 Inhoud response
boards/{id} 200 Één bestuursobject, behorende bij het {id}.
boards/{id} 404 Melding: "Board with id {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.