OSR:API/V2/Opvragen endpoints

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

Aanroep

API endpoint

GET	/endpoints

Voorbeeld

GET /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	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
include_future_endpoints	Hiermee wordt aangegeven dat toekomstige endpoints moeten worden teruggegeven.	Optioneel

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

Response

Voorbeeld

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"}, 
         "system": {"href": "/api/v2/systems/f00b0da0-d8a1-45a7-8c09-24dadb38b346"}
      } 
   }, 
      { 
      "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"}, 
         "system": {"href": "/api/v2/systems/cee3f52a-4044-4dce-8912-47bc09aafcf7"} 
      } 
   } 
]

Veld	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
_links system	Direct link om informatie van het gekoppelde systeem op te vragen. Dit veld is optioneel per dienst.

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

Codes

Route	Code	Inhoud response
endpoints	200	Een lijst van endpoint-objecten of een lege lijst.
endpoints	400	Melding: "Validation errors".
endpoints/{id}	200	Één endpoint-object, behorende bij het {id}.
endpoints/{id}	404	Melding: "Endpoint 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

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.