OSR:2019/Opvragen endpoints: verschil tussen versies

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken
(Response)
(Voor wie?)
 
(11 tussenliggende versies door 2 gebruikers niet weergegeven)
Regel 1: Regel 1:
 
==Inleiding==
 
==Inleiding==
 
Het endpoint bevat de url waarmee de leverancier namens de onderwijsinstelling communiceert.<br>
 
Het endpoint bevat de url waarmee de leverancier namens de onderwijsinstelling communiceert.<br>
Men kan het endpoint van een specifiek administratiekenmerk opvragen of alle endpoints behorende bij een onderwijsinstelling<br>
+
Men kan het endpoint van een specifiek routeringskenmerk opvragen of alle endpoints behorende bij een onderwijsinstelling<br>
 
Het opvragen van endpoints zal worden gelimiteerd om te voorkomen dat partijen het OSR volledig uitlezen.<br>
 
Het opvragen van endpoints zal worden gelimiteerd om te voorkomen dat partijen het OSR volledig uitlezen.<br>
 
  
 
==Opvragen endpoint==
 
==Opvragen endpoint==
Regel 9: Regel 8:
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
/api/v1/endpoints?service_version_namespace=http://xml.eld.nl/schemas/VVA/20181101&school_oin=0000000700004HR00000
+
/api/v2/endpoints?service_version_namespace=http://xml.eld.nl/schemas/VVA/20181101&school_oin=0000000700004HR00000
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Regel 19: Regel 18:
 
!  
 
!  
 
|-
 
|-
| | administration_id of school_oin
+
| | routing_id of school_oin
| Dit is om specifiek een administratiekenmerk te bevragen of alle endpoints behorende bij een school_oin*
+
| Dit is om specifiek een routeringskenmerk te bevragen of alle endpoints behorende bij een school_oin*
 
| | Verplicht
 
| | Verplicht
 
|-
 
|-
Regel 37: Regel 36:
 
|}
 
|}
  
'''* De response is leeg of bevat 1 endpoint indien administration_id is opgegeven '''<br>
+
'''* De response is leeg of bevat 1 endpoint indien routing_id is opgegeven '''<br>
  
 
==Response==
 
==Response==
Regel 46: Regel 45:
 
      { 
 
      { 
 
      "attributes": "endpoint1", 
 
      "attributes": "endpoint1", 
      "administration_id": "0000000700004HR7778D", 
+
      "routing_id": "0000000700099AA00003", 
 
      "url": "https://magister-schoolmaster.nl/vroegtijdig-aanmelden-mbo/123a132", 
 
      "url": "https://magister-schoolmaster.nl/vroegtijdig-aanmelden-mbo/123a132", 
 
      "start_date": "2017-12-18", 
 
      "start_date": "2017-12-18", 
 
      "end_date": "2019-12-18", 
 
      "end_date": "2019-12-18", 
 
      "_links":       { 
 
      "_links":       { 
         "self": {"href": "/api/v1/endpoints/9"}, 
+
         "self": {"href": "/api/v2/endpoints/9"}, 
         "school": {"href": "/api/v1/schools/10"}, 
+
         "school": {"href": "/api/v2/schools/10"}, 
         "service": {"href": "/api/v1/services/1"}, 
+
         "service": {"href": "/api/v2/services/1"}, 
         "service-version": {"href": "/api/v1/service-versions/4"} 
+
         "service-version": {"href": "/api/v2/service-versions/4"} 
 
      } 
 
      } 
 
   }, 
 
   }, 
 
      { 
 
      { 
 
      "attributes": "endpoint2", 
 
      "attributes": "endpoint2", 
      "administration_id": "0000000700004HR7778E", 
+
      "routing_id": "0000000700099AA00005", 
 
      "url": "https://elk.nl/vroegtijdig-aanmelden-mbo/123a132", 
 
      "url": "https://elk.nl/vroegtijdig-aanmelden-mbo/123a132", 
 
      "start_date": "2018-12-18", 
 
      "start_date": "2018-12-18", 
 
      "end_date": "2019-12-18", 
 
      "end_date": "2019-12-18", 
 
      "_links":       { 
 
      "_links":       { 
         "self": {"href": "/api/v1/endpoints/10"}, 
+
         "self": {"href": "/api/v2/endpoints/10"}, 
         "school": {"href": "/api/v1/schools/10"}, 
+
         "school": {"href": "/api/v2/schools/10"}, 
         "service": {"href": "/api/v1/services/1"}, 
+
         "service": {"href": "/api/v2/services/1"}, 
         "service-version": {"href": "/api/v1/service-versions/4"} 
+
         "service-version": {"href": "/api/v2/service-versions/4"} 
 
      } 
 
      } 
 
   } 
 
   } 
Regel 76: Regel 75:
 
! style="text-align:left;"| Parameters
 
! style="text-align:left;"| Parameters
 
! style="text-align:left;"| Omschrijving
 
! style="text-align:left;"| Omschrijving
!
 
 
|-
 
|-
 
| | attributes
 
| | attributes
 
| Attributen die zijn ingegeven voor dit endpoint. Veld kan leeg zijn
 
| Attributen die zijn ingegeven voor dit endpoint. Veld kan leeg zijn
 
|-
 
|-
| | administration_id
+
| | routing_id
| Het administratiekenmerk
+
| Het routeringskenmerk
 
|-
 
|-
 
| | url
 
| | url
Regel 106: Regel 104:
 
|}
 
|}
  
De lijst is leeg of bevat 1 endpoint indien administration_id is opgegeven<br>
+
De lijst is leeg of bevat 1 endpoint indien routing_id is opgegeven<br>
 
De lijst is leeg of bevat 1 of meerdere endpoints indien onderwijsinstelling_oin is opgegeven<br>
 
De lijst is leeg of bevat 1 of meerdere endpoints indien onderwijsinstelling_oin is opgegeven<br>
 
De lijst is leeg [], als geen endpoint matcht<br>
 
De lijst is leeg [], als geen endpoint matcht<br>
Regel 112: Regel 110:
  
  
Foutcodes
+
Response codes
  
 
{|class="wikitable"
 
{|class="wikitable"
Regel 126: Regel 124:
 
| | 400
 
| | 400
 
| | some error in query params
 
| | some error in query params
 +
|-
 +
| | endpoints/{id}
 +
| | 200
 +
| | endpoint object
 +
|-
 +
| | endpoints/{id}
 +
| | 404
 +
| | endpoint with {id} does not exist
 
|}
 
|}
  
Regel 131: Regel 137:
 
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>
  
{| cellspacing="5" cellpadding="0" style="margin:0em 0em 1em 0em; border:1px solid #1DA0E7; background:#fffdc4;width:100%"
+
{{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.}}
| ''' 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]]

Huidige versie van 15 jun 2020 om 14:49

Inleiding

Het endpoint bevat de url waarmee de leverancier namens de onderwijsinstelling communiceert.
Men kan het endpoint van een specifiek routeringskenmerk opvragen of alle endpoints behorende bij een onderwijsinstelling
Het opvragen van endpoints zal worden gelimiteerd om te voorkomen dat partijen het OSR volledig uitlezen.

Opvragen endpoint

Onderstaande is een voorbeeld van het request:

/api/v2/endpoints?service_version_namespace=http://xml.eld.nl/schemas/VVA/20181101&school_oin=0000000700004HR00000


Parameters Omschrijving Verplicht/Optioneel
routing_id of school_oin Dit is om specifiek een routeringskenmerk te bevragen of alle endpoints behorende bij een school_oin* Verplicht
service_version_namespace Namespace van de dienst Verplicht
attributes Hier kan gezocht worden op specifieke attributen.

Dit zal in eerste instantie nog niet veel gebruikt worden, maar kan later gebruikt worden om bijvoorbeeld te zoeken op type LAS/RIS etc...

Optioneel
Reference_date Datumveld om een endpoint welke bijvoorbeeld in de toekomst is ingesteld op te vragen. Optioneel

* De response is leeg of bevat 1 endpoint indien routing_id is opgegeven

Response

Het volgende response kan terug worden gegeven (onderstaand voorbeeld is voor school_oin):

[ 
      { 
      "attributes": "endpoint1", 
      "routing_id": "0000000700099AA00003", 
      "url": "https://magister-schoolmaster.nl/vroegtijdig-aanmelden-mbo/123a132", 
      "start_date": "2017-12-18", 
      "end_date": "2019-12-18", 
      "_links":       { 
         "self": {"href": "/api/v2/endpoints/9"}, 
         "school": {"href": "/api/v2/schools/10"}, 
         "service": {"href": "/api/v2/services/1"}, 
         "service-version": {"href": "/api/v2/service-versions/4"} 
      } 
   }, 
      { 
      "attributes": "endpoint2", 
      "routing_id": "0000000700099AA00005", 
      "url": "https://elk.nl/vroegtijdig-aanmelden-mbo/123a132", 
      "start_date": "2018-12-18", 
      "end_date": "2019-12-18", 
      "_links":       { 
         "self": {"href": "/api/v2/endpoints/10"}, 
         "school": {"href": "/api/v2/schools/10"}, 
         "service": {"href": "/api/v2/services/1"}, 
         "service-version": {"href": "/api/v2/service-versions/4"} 
      } 
   } 
]
Parameters Omschrijving
attributes Attributen die zijn ingegeven voor dit endpoint. Veld kan leeg zijn
routing_id Het routeringskenmerk
url De technische locatie van het endpoint
start_date Start datum van het endpoint
end_date Direct link om het endpoint op te kunnen vragen.
_links self Eind datum van het endpoint
_links school Direct link om informatie van de gekoppelde onderwijsinstelling op te vragen
_links service Direct link om informatie van de gekoppelde dienst op te vragen
_links service_version Direct link om informatie van de gekoppelde service version namespace op te vragen

De lijst is leeg of bevat 1 endpoint indien routing_id is opgegeven
De lijst is leeg of bevat 1 of meerdere endpoints indien onderwijsinstelling_oin is opgegeven
De lijst is leeg [], als geen endpoint matcht


Response codes

Route Code Melding
endpoints 200 endpoint object of lege array
endpoints 400 some error in query params
endpoints/{id} 200 endpoint object
endpoints/{id} 404 endpoint 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

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.