OSR:API/V2/Opvragen endpoints: verschil tussen versies
k (→Voorbeeld) |
|||
(28 tussenliggende versies door 3 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 |
+ | 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== |
||
+ | |||
− | Onderstaande is een voorbeeld van het request:<br> |
||
+ | ===Aanroep=== |
||
+ | |||
+ | ====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";> /endpoints</syntaxhighlight></td> |
||
+ | </tr></table> |
||
+ | |||
+ | |||
+ | ====Voorbeeld==== |
||
<syntaxhighlight lang="json"> |
<syntaxhighlight lang="json"> |
||
− | /api/ |
+ | GET /api/v2/endpoints?service_version_namespace=http://xml.eld.nl/schemas/VVA/20181101&school_oin=0000000700004HR00000 |
</syntaxhighlight> |
</syntaxhighlight> |
||
Regel 17: | Regel 26: | ||
! style="text-align:left;"| Omschrijving |
! style="text-align:left;"| Omschrijving |
||
! style="text-align:left;"| Verplicht/Optioneel |
! style="text-align:left;"| Verplicht/Optioneel |
||
− | ! |
||
|- |
|- |
||
− | | | |
+ | | | routing_id of school_oin |
− | | Dit is om specifiek een |
+ | | Dit is om specifiek een routeringskenmerk te bevragen * of alle endpoints behorende bij een school |
| | Verplicht |
| | Verplicht |
||
|- |
|- |
||
Regel 32: | Regel 40: | ||
| | Optioneel |
| | Optioneel |
||
|- |
|- |
||
− | | | |
+ | | | reference_date |
| Datumveld om een endpoint welke bijvoorbeeld in de toekomst is ingesteld op te vragen. |
| 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 |
| | Optioneel |
||
|} |
|} |
||
− | + | ''* De response is leeg of bevat 1 endpoint indien routing_id is opgegeven ''<br> |
|
+ | |||
+ | ===Response=== |
||
− | == |
+ | ====Voorbeeld==== |
Het volgende response kan terug worden gegeven (onderstaand voorbeeld is voor school_oin):<br> |
Het volgende response kan terug worden gegeven (onderstaand voorbeeld is voor school_oin):<br> |
||
Regel 46: | Regel 60: | ||
{ |
{ |
||
"attributes": "endpoint1", |
"attributes": "endpoint1", |
||
− | " |
+ | "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/ |
+ | "self": {"href": "/api/v2/endpoints/9"}, |
− | "school": {"href": "/api/ |
+ | "school": {"href": "/api/v2/schools/10"}, |
− | "service": {"href": "/api/ |
+ | "service": {"href": "/api/v2/services/1"}, |
− | "service-version": {"href": "/api/ |
+ | "service-version": {"href": "/api/v2/service-versions/4"}, |
+ | "system": {"href": "/api/v2/systems/f00b0da0-d8a1-45a7-8c09-24dadb38b346"} |
||
} |
} |
||
}, |
}, |
||
{ |
{ |
||
"attributes": "endpoint2", |
"attributes": "endpoint2", |
||
− | " |
+ | "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/ |
+ | "self": {"href": "/api/v2/endpoints/10"}, |
− | "school": {"href": "/api/ |
+ | "school": {"href": "/api/v2/schools/10"}, |
− | "service": {"href": "/api/ |
+ | "service": {"href": "/api/v2/services/1"}, |
− | "service-version": {"href": "/api/ |
+ | "service-version": {"href": "/api/v2/service-versions/4"}, |
+ | "system": {"href": "/api/v2/systems/cee3f52a-4044-4dce-8912-47bc09aafcf7"} |
||
} |
} |
||
} |
} |
||
Regel 74: | Regel 90: | ||
{|class="wikitable" |
{|class="wikitable" |
||
− | ! style="text-align:left;"| |
+ | ! style="text-align:left;"| Veld |
! 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 |
||
|- |
|- |
||
+ | | | routing_id |
||
− | | | administration_id |
||
− | | Het |
+ | | Het routeringskenmerk |
|- |
|- |
||
| | url |
| | url |
||
Regel 104: | Regel 119: | ||
| | _links service_version |
| | _links service_version |
||
| Direct link om informatie van de gekoppelde service version namespace op te vragen |
| 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 |
+ | 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> |
||
+ | |||
+ | ====Codes==== |
||
+ | |||
+ | {|class="wikitable" |
||
+ | ! style="text-align:left;"| Route |
||
+ | ! style="text-align:left;"| Code |
||
+ | ! style="text-align:left;"| 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?== |
==Voor wie?== |
||
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 |
+ | Zie meer informatie over de API op https://osr.kennisnet.nl/api/v2/documentation<br> |
+ | ==Over het gebruik van certificaten== |
||
− | {| 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.}} |
⚫ | |||
+ | |||
+ | [[Category:OSR]] |
Huidige versie van 21 mrt 2023 om 09:29
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