OSR:API/V2/toevoegen en wijzigen van endpoints: verschil tussen versies

Huidige versie van 4 nov 2022 om 14:43

Inleiding

De leverancier moet de informatie over het endpoint zelf aanleveren.
Dit wijkt af van het OSO-project, waar een school in eerste instantie het endpoint (aanleverpunt) aanmaakt en de leverancier vervolgens het afleveradres erbij opslaat middels de call registreer aanleverpunt.

Om een endpoint aan te maken of te modificeren moet de leverancier gemandateerd zijn en het mandaat token gebruiken in de aanvraag voor het aanmaken van het endpoint.

Endpoints zijn specifiek voor een dienstversie en er kan eventueel ook een ingangsdatum worden meegegeven.

Opvragen mandaat token

Voordat men een endpoint kan registreren voor een bepaalde dienst, moet de onderwijsinstelling uw organisatie een mandaat hebben gegeven voor deze dienst.
Voor het registreren van een endpoint moet het token dat hoort bij het mandaat worden opgehaald.

Het opvragen van een mandaat token, is identiek aan het bericht valideren mandaat. Het verschil is dat hier het mandaat van uw eigen organisatie wordt opgevraagd.

Op de volgende pagina is het opvragen van een mandaat token uitgelegd: Opvragen mandaat token

Het registreren van een endpoint

Onderstaand staat beschreven hoe een endpoint te registreren.

Let op:
Deze functionaliteit vereist authenticatie met behulp van een API key. Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).

Aanroep

API endpoint

POST	/endpoints

Voorbeeld

{ 
"mandate_token": "6a47bfdd-81a7-46cd-b41f-d907e91ebdfc", 
"routing_id": "0000000700004HR77707", 
"service_version_namespace": "http://xml.eld.nl/schemas/Overstapservice/20170601", 
"url": "https://t2.nl", 
"attributes": "LAS", 
"start_date": "2019-01-01", 
"end_date": "2020-01-01" 
}

Parameters	Omschrijving	Verplicht/Optioneel
mandate_token	Het mandaat token welke verkregen is door het mandaat op te vragen	Verplicht
routing_id	Uniek routeringskenmerk. Dit moet goed afgestemd worden met de onderwijsinstelling, om eventuele problemen te voorkomen bij meerdere leveranciers die gemandateerd zijn voor de onderwijsinstelling en dienst combinatie.	Verplicht
service_version_namespace	Namespace van de dienst	Verplicht
url	Technische locatie van de leverancier	Verplicht
attributes	Mogelijke attributen die ook opgeslagen moeten worden bij dit endpoint	Optioneel
start_date*	Start datum van het endpoint. Indien dit niet meegegeven wordt, dan wordt de huidige datum hier automatisch ingevuld. start datum kan niet in het verleden liggen. LET OP, startdatum van endpoint mag niet voor de startdatum van het mandaat liggen.	Optioneel
end_date*	Eind datum van het endpoint. Einddatum kan niet in het verleden liggen	Optioneel

*start_date: middernacht aan het begin van de opgegeven datum
*end_date: middernacht aan het einde van de opgegeven dag

Response

Voorbeeld

{
	"attributes": "",
	"routing_id": "0000000700004HR777AA",
	"url": "https://t2.nl",
	"start_date": "2019-01-31",
	"end_date": null,
	"_links": {
		"self": {
			"href": "/api/v2/endpoints/21"
		},
		"school": {
			 "href": "/api/v2/schools/10"
		},
		"service": {
			"href": "/api/v2/services/1"
		},
		"service-version": {
			"href": "/api/v2/service-versions/4"
		}
	}
}

Codes

Route	Code	Inhoud response
endpoints	201	Het endpoint-object, welke is aangemaakt.
endpoints	400	Melding: "Endpoint already exists. Combination of routing id and service version is already created".
endpoints	403	Melding: "Not allowed, mandate expired".

Het wijzigen van een endpoint

Het wijzigen van een endpoint is vrijwel hetzelfde als het registreren van een endpoint. De enige uitzondering hier is dat het Id van het endpoint meegestuurd moet worden.
Het Id is al eerder verkregen bij het registreren van het endpoint. Het mandaat token hoeft hier niet meegestuurd te worden.

Let op:
Deze functionaliteit vereist authenticatie met behulp van een API key. Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).

Aanroep

API endpoint

PUT	/endpoints

Voorbeeld

PUT https://osr-t.kennisnet.nl/api/v2/endpoints/21
{
	"routing_id": "0000000700004HR77707",
	"service_version_namespace": "http://xml.eld.nl/schemas/Overstapservice/20170601",
	"url": "https://t2.nl"
}

Response

Codes

Route	Code	Inhoud response
endpoints/{id}	201	Het endpoint-object, welke is bijgewerkt.
endpoints/{id}	400	Melding: "Validation errors found".
endpoints/{id}	403	Melding: "Not allowed, mandate expired".

Het kopiëren van endpoints naar een nieuwe dienstversie

Als systeem kun je alle endpoints, welke je voor een bepaalde dienstversie hebt geregistreerd met één enkele aanroep kopiëren naar een nieuwere versie van de dienst. Voorwaarde voor het gebruik hiervan is dat de nieuwere dienstversie nog geen actieve endpoints van het betreffende systeem bevat.

Na het kopiëren van de endpoints:

Hebben de nieuwe endpoints een startdatum van het moment van kopiëren;
Hebben de nieuwe endpoint geen einddatum;
Is het routeringskenmerk overgenomen van het oude endpoint.

Let op:
Deze functionaliteit vereist authenticatie met behulp van een API key. Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).

Aanroep

API endpoint

POST	/service-versions/copy-endpoints-from-service-version

Voorbeeld

{
	"service_version_namespace_to_copy_to" => "http://xml.eld.nl/schemas/Overstapservice/20220404",
    "service_version_namespace_to_copy_from" => "http://xml.eld.nl/schemas/Overstapservice/20210601"
}

Reponse

Codes

Code	Inhoud response
200	Het dienstversie-object (kopieerbestemming)
400	Melding: "Validation error(s)".
404	Melding: "Service version with namespace {namespace} does not exist".

Voor wie?

Deze service is beschikbaar voor leveranciers die gekwalificeerd zijn voor het OSR en die gemandateerd zijn voor een onderwijsinstelling.
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

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.

OSR:API/V2/toevoegen en wijzigen van endpoints: verschil tussen versies

Huidige versie van 4 nov 2022 om 14:43

Inhoud

Inleiding

Opvragen mandaat token

Het registreren van een endpoint

Aanroep

API endpoint

Voorbeeld

Response

Voorbeeld

Codes

Het wijzigen van een endpoint

Aanroep

API endpoint

Voorbeeld

Response

Codes

Het kopiëren van endpoints naar een nieuwe dienstversie

Aanroep

API endpoint

Voorbeeld

Reponse

Codes

Voor wie?

Navigatiemenu

Zoeken

@@ Regel 16: / Regel 16: @@
 Op de volgende pagina is het opvragen van een mandaat token uitgelegd: [[OSR:2019/Opvragen_mandaat_token|Opvragen mandaat token]]
-==Registreren endpoint==
+==Het registreren van een endpoint==
+Onderstaand staat beschreven hoe een endpoint te registreren.
-{{Info|''' Let op:'''<br>Bij deze service moet er ook een JWT token worden meegegeven. Op de volgende pagina kan nadere informatie omtrent JWT gevonden worden: [[OSR:2019/JWT|JWT]]}}
+{{Info|''' Let op:'''<br>Deze functionaliteit vereist authenticatie met behulp van een API key. Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).}}
+===Aanroep===
-Hieronder is een voorbeeld weergegeven van de operatie:
+====API endpoint====
+<table><tr>
+<td><span style="color:white;font-weight:bold;background-color:#61affe;padding:6px 15px">POST</span></td>
+<td><syntaxhighlight lang="json" style="display:inline";> /endpoints</syntaxhighlight></td>
+</tr></table>
+====Voorbeeld====
 <syntaxhighlight lang="json">
-POST /api/v1/endpoints
 {
 "mandate_token": "6a47bfdd-81a7-46cd-b41f-d907e91ebdfc",
-"administration_id": "0000000700004HR77707",
+"routing_id": "0000000700004HR77707",
 "service_version_namespace": "http://xml.eld.nl/schemas/Overstapservice/20170601",
 "url": "https://t2.nl",
@@ Regel 33: / Regel 40: @@
 "end_date": "2020-01-01"
 }
-Request Headers
-JWT:
-eyJhbGciOiJSUz …
 </syntaxhighlight>
 {|class="wikitable"
@@ Regel 52: / Regel 52: @@
 | | Verplicht
 |-
+| | routing_id
-| | administration_id
-| Uniek administratie kenmerk.<br>Dit moet goed afgestemd worden met de onderwijsinstelling, om eventuele problemen te voorkomen bij meerdere leveranciers die gemandateerd zijn voor de onderwijsinstelling en dienst combinatie.
+| Uniek routeringskenmerk.<br>Dit moet goed afgestemd worden met de onderwijsinstelling, om eventuele problemen te voorkomen bij meerdere leveranciers die gemandateerd zijn voor de onderwijsinstelling en dienst combinatie.
 | | Verplicht
 |-
@@ Regel 80: / Regel 80: @@
 '''*end_date: middernacht aan het einde van de opgegeven dag
-==Response==
+===Response===
+====Voorbeeld====
 <syntaxhighlight lang="json">
 {
 	"attributes": "",
-	"administration_id": "0000000700004HR777AA",
+	"routing_id": "0000000700004HR777AA",
-	"url": "https:\/\/t2.nl",
+	"url": "https://t2.nl",
 	"start_date": "2019-01-31",
 	"end_date": null,
 	"_links": {
 		"self": {
-			"href": "\/api\/v1\/endpoints\/21"
+			"href": "/api/v2/endpoints/21"
 		},
 		"school": {
-			"href": "\/api\/v1\/schools\/10"
+			 "href": "/api/v2/schools/10"
 		},
 		"service": {
-			"href": "\/api\/v1\/services\/1"
+			"href": "/api/v2/services/1"
 		},
 		"service-version": {
-			"href": "\/api\/v1\/service-versions\/4"
+			"href": "/api/v2/service-versions/4"
 		}
 	}
@@ Regel 107: / Regel 108: @@
+====Codes====
-Foutcodes
 {|class="wikitable"
 ! style="text-align:left;"| Route
 ! style="text-align:left;"| Code
-! style="text-align:left;"| Melding
+! style="text-align:left;"| Inhoud response
 |-
 | | endpoints
-| | 200
+| | 201
-| | endpoint object
+| | Het endpoint-object, welke is aangemaakt.
 |-
 | | endpoints
 | | 400
+| | Melding: "Endpoint already exists. Combination of routing id and service version is already created".
-| | invalid json message received
-|-
-| | endpoints
-| | 400
-| | some error in query params (jwt token, date etc..)
 |-
 | | endpoints
 | | 403
+| | Melding: "Not allowed, mandate expired".
-| | you are not qualified to create an endpoint
 |}
-==Updaten endpoint==
+==Het wijzigen van een endpoint==
-Het updaten van een endpoint is vrijwel hetzelfde als het registreren van een endpoint.
+Het wijzigen van een endpoint is vrijwel hetzelfde als het registreren van een endpoint.
-Enige uitzondering hier is dat het Id van het endpoint meegestuurd moet worden.<br>
+De enige uitzondering hier is dat het Id van het endpoint meegestuurd moet worden.<br>
-Het Id is al eerder verkregen bij het registreren van het endpoint. Mandaat token hoeft niet meegestuurd te worden.
+Het Id is al eerder verkregen bij het registreren van het endpoint. Het mandaat token hoeft hier niet meegestuurd te worden.
+{{Info|''' Let op:'''<br>Deze functionaliteit vereist authenticatie met behulp van een API key. Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).}}
+===Aanroep===
+====API endpoint====
+<table><tr>
+<td><span style="color:white;font-weight:bold;background-color:#61affe;padding:6px 15px">PUT</span></td>
+<td><syntaxhighlight lang="json" style="display:inline";> /endpoints</syntaxhighlight></td>
+</tr></table>
+====Voorbeeld====
 <syntaxhighlight lang="json">
-PUT https://osr-t.kennisnet.nl/api/v1/endpoints/21
+PUT https://osr-t.kennisnet.nl/api/v2/endpoints/21
 {
-	"administration_id": "0000000700004HR77707",
+	"routing_id": "0000000700004HR77707",
 	"service_version_namespace": "http://xml.eld.nl/schemas/Overstapservice/20170601",
 	"url": "https://t2.nl"
@@ Regel 150: / Regel 157: @@
+===Response===
-Foutcodes
+====Codes====
 {|class="wikitable"
 ! style="text-align:left;"| Route
 ! style="text-align:left;"| Code
-! style="text-align:left;"| Melding
+! style="text-align:left;"| Inhoud response
 |-
 | | endpoints/{id}
-| | 200
+| | 201
-| | endpoint object
+| | Het endpoint-object, welke is bijgewerkt.
 |-
 | | endpoints/{id}
 | | 400
+| | Melding: "Validation errors found".
-| | invalid json message received
-|-
-| | endpoints/{id}
-| | 400
-| | some error in query params (jwt token, date etc..)
 |-
 | | endpoints/{id}
 | | 403
+| | Melding: "Not allowed, mandate expired".
-| | you are not qualified to update an endpoint
+|}
+==Het kopiëren van endpoints naar een nieuwe dienstversie==
+Als systeem kun je alle endpoints, welke je voor een bepaalde dienstversie hebt geregistreerd met één enkele aanroep kopiëren naar een nieuwere versie van de dienst. Voorwaarde voor het gebruik hiervan is dat de nieuwere dienstversie nog geen actieve endpoints van het betreffende systeem bevat.<br>
+<br>
+Na het kopiëren van de endpoints:
+* Hebben de nieuwe endpoints een startdatum van het moment van kopiëren;
+* Hebben de nieuwe endpoint geen einddatum;
+* Is het routeringskenmerk overgenomen van het oude endpoint.
+{{Info|''' Let op:'''<br>Deze functionaliteit vereist authenticatie met behulp van een API key. Meer informatie over het gebruik hiervan staat vermeld in de API documentatie (link op de hoofdpagina).}}
+===Aanroep===
+====API endpoint====
+<table><tr>
+<td><span style="color:white;font-weight:bold;background-color:#61affe;padding:6px 15px">POST</span></td>
+<td><syntaxhighlight lang="json" style="display:inline";> /service-versions/copy-endpoints-from-service-version</syntaxhighlight></td>
+</tr></table>
+====Voorbeeld====
+<syntaxhighlight lang="json">
+{
+	"service_version_namespace_to_copy_to" => "http://xml.eld.nl/schemas/Overstapservice/20220404",
+    "service_version_namespace_to_copy_from" => "http://xml.eld.nl/schemas/Overstapservice/20210601"
+}
+</syntaxhighlight>
+===Reponse===
+====Codes====
+{|class="wikitable"
+! style="text-align:left;"| Code
+! style="text-align:left;"| Inhoud response
+|-
+| | 200
+| | Het dienstversie-object (kopieerbestemming)
+|-
+| | 400
+| | Melding: "Validation error(s)".
 |-
-| | endpoints/{id}
 | | 404
+| | Melding: "Service version with namespace {namespace} does not exist".
-| | endpoint not found
 |}
@@ Regel 181: / Regel 226: @@
 Deze service is beschikbaar voor leveranciers die gekwalificeerd zijn voor het OSR en die gemandateerd zijn voor een onderwijsinstelling.<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/v1/documentation<br>
+Zie meer informatie over de API op https://osr.kennisnet.nl/api/v2/documentation<br>
 {{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.}}