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

Uit Kennisnet Developers Documentatie
< OSR:API‎ | V2
Naar navigatie springen Naar zoeken springen
(52 tussenliggende versies door 3 gebruikers niet weergegeven)
Regel 7: Regel 7:
 
Endpoints zijn specifiek voor een dienstversie en er kan eventueel ook een ingangsdatum worden meegegeven.<br>
  
Endpoints zijn specifiek voor een dienstversie en er kan eventueel ook een ingangsdatum worden meegegeven.<br>
   
  +
==Opvragen mandaat token==
−
Bij deze service moet er ook een JWT token worden meegegeven. Hieronder is een link opgenomen hoe JWT toegepast moet worden voor het OSR<br>
  
   
  +
Voordat men een endpoint kan registreren voor een bepaalde dienst, moet de onderwijsinstelling uw organisatie een mandaat hebben gegeven voor deze dienst.<br>
  +
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.<br>
−
==Post endpoints==
  
  +
−
Hieronder is een voorbeeld weergegeven van de POST operatie:
 
  +
Op de volgende pagina is het opvragen van een mandaat token uitgelegd: [[OSR:2019/Opvragen_mandaat_token|Opvragen mandaat token]]
−
 
  +
−
/api/v1/endpoints<br>
  
  +
==Registreren 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).}}
  +
  +
Hieronder is een voorbeeld weergegeven van de operatie:
   
 
<syntaxhighlight lang="json">
  
<syntaxhighlight lang="json">
  +
POST /api/v2/endpoints
 
{
 
{
 
"mandate_token": "6a47bfdd-81a7-46cd-b41f-d907e91ebdfc",
 
"mandate_token": "6a47bfdd-81a7-46cd-b41f-d907e91ebdfc",
−
"administration_id": "0000000700004HR77707",
+
"routing_id": "0000000700004HR77707",
 
"service_version_namespace": "http://xml.eld.nl/schemas/Overstapservice/20170601",
 
"service_version_namespace": "http://xml.eld.nl/schemas/Overstapservice/20170601",
 
"url": "https://t2.nl",
 
"url": "https://t2.nl",
Regel 25: Regel 33:
 
"end_date": "2020-01-01"
 
"end_date": "2020-01-01"
 
}
 
}
−  
−
Request Headers
 
−
JWT:
 
−
 
−
eyJhbGciOiJSUz …
 
 
</syntaxhighlight>
  
</syntaxhighlight>
−  
−
Op de volgende pagina kan nadere informatie omtrent JWT gevonden worden:
  
−
[[OSR:2019/JWT|JWT]]
  
   
 
{|class="wikitable"
  
{|class="wikitable"
Regel 45: Regel 45:
 
| | Verplicht
  
| | 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 routerings 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.
 
| | Verplicht
  
| | Verplicht
 
|-
  
|-
Regel 62: Regel 62:
 
|-
  
|-
 
| | start_date*
  
| | start_date*
−
| Start datum van het endpoint. <br>Indien dit niet meegegeven wordt, dan wordt de huidige datum hier automatisch ingevuld. start datum kan niet in het verleden liggen.
 +
| Start datum van het endpoint. <br>Indien dit niet meegegeven wordt, dan wordt de huidige datum hier automatisch ingevuld. start datum kan niet in het verleden liggen.<br> LET OP, startdatum van endpoint mag niet voor de startdatum van het mandaat liggen.
 
| | Optioneel
  
| | Optioneel
 
|-
  
|-
Regel 72: Regel 72:
 
'''*start_date: middernacht aan het begin van de opgegeven datum<br>
  
'''*start_date: middernacht aan het begin van de opgegeven datum<br>
 
'''*end_date: middernacht aan het einde van de opgegeven dag
  
'''*end_date: middernacht aan het einde van de opgegeven dag
  +
  +
==Response==
  +
  +
<syntaxhighlight lang="json">
  +
{
  +
"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"
  +
}
  +
}
  +
}
  +
</syntaxhighlight>
  +
  +
  +
Response codes
  +
  +
{|class="wikitable"
  +
! style="text-align:left;"| Route
  +
! style="text-align:left;"| Code
  +
! style="text-align:left;"| Melding
  +
|-
  +
| | endpoints
  +
| | 201
  +
| | endpoint object
  +
|-
  +
| | endpoints
  +
| | 400
  +
| | invalid json message received
  +
|-
  +
| | endpoints
  +
| | 400
  +
| | some error in query params (jwt token, date etc..)
  +
|-
  +
| | endpoints
  +
| | 403
  +
| | you are not qualified to create an endpoint
  +
  +
|}
  +
  +
==Updaten 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).}}
  +
  +
Het updaten 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>
  +
Het Id is al eerder verkregen bij het registreren van het endpoint. Mandaat token hoeft niet meegestuurd te worden.
  +
  +
<syntaxhighlight lang="json">
  +
  +
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"
  +
}
  +
</syntaxhighlight>
  +
  +
  +
  +
Response codes
  +
  +
{|class="wikitable"
  +
! style="text-align:left;"| Route
  +
! style="text-align:left;"| Code
  +
! style="text-align:left;"| Melding
  +
|-
  +
| | endpoints/{id}
  +
| | 201
  +
| | endpoint object
  +
|-
  +
| | endpoints/{id}
  +
| | 400
  +
| | invalid json message received
  +
|-
  +
| | endpoints/{id}
  +
| | 400
  +
| | some error in query params (jwt token, date etc..)
  +
|-
  +
| | endpoints/{id}
  +
| | 403
  +
| | you are not qualified to update an endpoint
  +
|-
  +
| | endpoints/{id}
  +
| | 404
  +
| | endpoint not found
  +
|}
   
 
==Voor wie?==
  
==Voor wie?==
−
Deze service is beschikbaar voor leveranciers die gekwalificeerd zijn voor het OSR en die gemandateerd zijn voor een onderwijsinstelling<br>
 +
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>
 +
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/doc<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.}}
  +
  +
[[Category:OSR]]

Versie van 22 jul 2020 14:53

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

Registreren endpoint

Info.gif 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).

Hieronder is een voorbeeld weergegeven van de operatie: 

POST /api/v2/endpoints
{ 
"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 routerings kenmerk.
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

{
	"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"
		}
	}
}


Response codes

Route Code Melding
endpoints 201 endpoint object
endpoints 400 invalid json message received
endpoints 400 some error in query params (jwt token, date etc..)
endpoints 403 you are not qualified to create an endpoint

Updaten endpoint

Info.gif 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).

Het updaten 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.
Het Id is al eerder verkregen bij het registreren van het endpoint. Mandaat token hoeft niet meegestuurd te worden. 

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 Melding
endpoints/{id} 201 endpoint object
endpoints/{id} 400 invalid json message received
endpoints/{id} 400 some error in query params (jwt token, date etc..)
endpoints/{id} 403 you are not qualified to update an endpoint
endpoints/{id} 404 endpoint not found

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

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.
Overgenomen van "https://developers.wiki.kennisnet.nl/index.php?title=OSR:API/V2/toevoegen_en_wijzigen_van_endpoints&oldid=10746"