OSR:API/V2/Valideren mandaat: verschil tussen versies

Uit Kennisnet Developers Documentatie
< OSR:API‎ | V2
Naar navigatie springen Naar zoeken springen
 
(22 tussenliggende versies door 2 gebruikers niet weergegeven)
Regel 1: Regel 1:
 
==Inleiding==
  
==Inleiding==
   
−
Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en administratiesysteem. Het mandaat zelf wordt aangemaakt door de OSR beheerder van de onderwijsinstelling via de grafische beheeromgeving van het OSR. <br>
 +
Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en systeem. Het mandaat zelf wordt aangemaakt door de OSR beheerder van de onderwijsinstelling via de grafische beheeromgeving van het OSR. <br>
   
−
Het is mogelijk voor andere partijen om te verifiëren of een administratiesysteem gemandateerd is namens een onderwijsinstelling voor een bepaalde dienst.<br><br>
 +
Het is mogelijk voor andere partijen om te verifiëren of een systeem gemandateerd is namens een onderwijsinstelling voor een bepaalde dienst.<br><br>
   
 
==Valideer mandaat==
  
==Valideer mandaat==
  +
===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";> /mandates</syntaxhighlight></td>
  +
</tr></table>
  +
  +
====Voorbeeld====
  +
 
Hieronder is een voorbeeld weergegeven van het request:<br>
  
Hieronder is een voorbeeld weergegeven van het request:<br>
   
 
<syntaxhighlight lang="json">
  
<syntaxhighlight lang="json">
−
/api/v1/mandates?supplier_oin=00000003272448340204&school_oin=0000000700000AV00000&service_version_namespace=http://xml.eld.nl/schemas/Overstapservice/20180404&reference_date=2019-01-01
 +
GET /api/v2/mandates?supplier_oin=00000003272448340204&school_oin=0000000700000AV00000&service_version_namespace=http://xml.eld.nl/schemas/Overstapservice/20180404&reference_date=2019-01-01
   
 
</syntaxhighlight>
  
</syntaxhighlight>
Regel 19: Regel 30:
 
|-
  
|-
 
| | School_oin
  
| | School_oin
−
| OIN van de onderwijsinstelling
 +
| OIN van de onderwijsinstelling.
 
| | Verplicht
  
| | Verplicht
 
|-
  
|-
 
| | Service_version_namespace *
  
| | Service_version_namespace *
−
| Namespace van de dienst
 +
| Namespace van de dienst. Wanneer leeggelaten, is een Service_code verplicht.
−
| | Verplicht
 +
| | Optioneel
 
|-
  
|-
 
| | Supplier_oin
  
| | Supplier_oin
−
| OIN van de leverancier
 +
| OIN van de leverancier, behorende bij het systeem.
 
| | Verplicht
  
| | Verplicht
 
|-
  
|-
 
| | Reference_date
  
| | Reference_date
−
| Datumveld om een mandaat welke bv in de toekomst is ingesteld op te vragen
 +
| Datumveld om een mandaat welke op een specifieke datum in de toekomst of het verleden is ingesteld op te vragen.
  +
| | Optioneel
  +
|-
  +
| | Service_code
  +
| Code van de dienst. Wanneer leeggelaten, is een Service_version_namespace verplicht.
 
| | Optioneel
  
| | Optioneel
 
|}
  
|}
   
−
<nowiki>*</nowiki> Om de verschillende versies van een dienst te kunnen onderscheiden wordt de namespace van de dienst gebruikt als uniek dienstkenmerk.<br>In de WSDL wordt dit meestal aangeduid met de targetnamespace. De namespace is een unieke URI die voor alle services/operaties in de dienst gebruikt worden.
 +
<nowiki>*</nowiki> Om de verschillende versies binnen een dienst te kunnen onderscheiden worden namespaces gebruikt als kenmerk. De namespace is een unieke URI die voor alle services/operaties gebruikt wordt.
   
 
==Response==
  
==Response==
   
  +
====Voorbeeld====
−
De volgende response kan terug worden gegeven:
  
   
 
<syntaxhighlight lang="json">
  
<syntaxhighlight lang="json">
Regel 45: Regel 60:
 
{
 
{
 
"code": 200,
 
"code": 200,
−
"message": "Mandate found"
+
"message": "Mandate for system exists and is valid"
 
}
 
}
 
</syntaxhighlight>
  
</syntaxhighlight>
   
  +
====Codes====
−
of 404 Mandate not found, indien er geen mandaat is gevonden voor de combinatie van opgegeven parameters.
  
−  
−  
−
Response codes
  
   
 
{|class="wikitable"
  
{|class="wikitable"
−
! style="text-align:left;"| Route
  
 
! style="text-align:left;"| Code
  
! style="text-align:left;"| Code
−
! style="text-align:left;"| Melding
 +
! style="text-align:left;"| Inhoud response
 
|-
  
|-
−
| | mandates
  
 
| | 200
  
| | 200
  +
| | Mandaatobject.<br>Deze response wordt gegeven wanneer de API-gebruiker het systeem is, behorende bij het mandaat.
−
| | mandate object
  
  +
|-
  +
| | 204
  +
| | Melding: "Mandate for system exists and is valid".<br>Deze response wordt gegeven wanneer de API-gebruiker niet het systeem is, behorende bij het mandaat.
 
|-
  
|-
−
| | mandates
  
 
| | 400
  
| | 400
  +
| | Melding: "There is a problem with the system query parameters".
−
| | some error in query params
  
 
|-
  
|-
−
| | mandates
  
 
| | 404
  
| | 404
−
| | mandate not found
 +
| | Melding: "Mandate not found".
 
|}
  
|}
   
 
==Eigen mandaat opvragen==
  
==Eigen mandaat opvragen==
−
Het is ook mogelijk om het eigen mandaat op te vragen. Het resultaat bevat een mandaat token wat van belang is bij het aanmaken van een endpoint.
 +
Het is ook mogelijk om als systeem het eigen mandaat of een lijst van mandaten voor een dienst op te vragen.
  +
Bij een specifiek mandaat bevat het resultaat een mandaat token, welke benodigd is bij het registreren van een endpoint.
   
−
Op de volgende pagina kunt u hier informatie over terugvinden: [[OSR:2019/Opvragen_mandaat_token|Opvragen mandaat token]]
 +
Op de volgende pagina kunt u hier informatie over terugvinden: [[OSR:API/V2/Opvragen_mandaat_token|Opvragen mandaat token]]
   
 
==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-api-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.}}
  
{{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.}}

Huidige versie van 21 jun 2023 om 11:09

Inleiding

Het mandaat legt de relatie vast tussen onderwijsinstelling, dienst en systeem. Het mandaat zelf wordt aangemaakt door de OSR beheerder van de onderwijsinstelling via de grafische beheeromgeving van het OSR.

Het is mogelijk voor andere partijen om te verifiëren of een systeem gemandateerd is namens een onderwijsinstelling voor een bepaalde dienst.

Valideer mandaat

Aanroep

API endpoint

GET 
 /mandates

Voorbeeld

Hieronder is een voorbeeld weergegeven van het request:

GET /api/v2/mandates?supplier_oin=00000003272448340204&school_oin=0000000700000AV00000&service_version_namespace=http://xml.eld.nl/schemas/Overstapservice/20180404&reference_date=2019-01-01
Parameters Omschrijving Verplicht/Optioneel
School_oin OIN van de onderwijsinstelling. Verplicht
Service_version_namespace * Namespace van de dienst. Wanneer leeggelaten, is een Service_code verplicht. Optioneel
Supplier_oin OIN van de leverancier, behorende bij het systeem. Verplicht
Reference_date Datumveld om een mandaat welke op een specifieke datum in de toekomst of het verleden is ingesteld op te vragen. Optioneel
Service_code Code van de dienst. Wanneer leeggelaten, is een Service_version_namespace verplicht. Optioneel

* Om de verschillende versies binnen een dienst te kunnen onderscheiden worden namespaces gebruikt als kenmerk. De namespace is een unieke URI die voor alle services/operaties gebruikt wordt.

Response

Voorbeeld

HTTP/1.1 200 OK 
{ 
   "code": 200, 
   "message": "Mandate for system exists and is valid" 
}

Codes

Code Inhoud response
200 Mandaatobject.
Deze response wordt gegeven wanneer de API-gebruiker het systeem is, behorende bij het mandaat.
204 Melding: "Mandate for system exists and is valid".
Deze response wordt gegeven wanneer de API-gebruiker niet het systeem is, behorende bij het mandaat.
400 Melding: "There is a problem with the system query parameters".
404 Melding: "Mandate not found".

Eigen mandaat opvragen

Het is ook mogelijk om als systeem het eigen mandaat of een lijst van mandaten voor een dienst op te vragen. Bij een specifiek mandaat bevat het resultaat een mandaat token, welke benodigd is bij het registreren van een endpoint.

Op de volgende pagina kunt u hier informatie over terugvinden: Opvragen mandaat token

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