| Info | ||
|---|---|---|
| ||
Het subscription interface hoort bij de /wiki/spaces/MedMijAfsprakenstelsel120/pages/135103542. Op deze pagina staan alleen de verantwoordelijkheden inzake het resource interface die nog niet genoemd staan in de OAuth 2-specificatie. |
...
| Info | ||
|---|---|---|
| ||
Het subscription interface hoort bij de /wiki/spaces/MedMijAfsprakenstelsel120/pages/135103542. Op deze pagina staan alleen de verantwoordelijkheden inzake het resource interface die nog niet genoemd staan in de OAuth 2-specificatie. |
1. De OAuth Client gebruikt voor het sturen van het acces token, in de subscription request, de methode Authorization Request Header Field, zoals beschreven in sectie 2.1 van RFC6750.
2. De subcription interface kent drie typen requests:
| subscription creation request | subscription duration request | subscription duration request | ||||||
|---|---|---|---|---|---|---|---|---|
| 2a. | voor het aanmaken van een nieuw Abonnement door een Persoon bij een Zorgaanbieder op (Notificaties over) deze Gegevensdienst | voor het wijzigen van de duur van een bestaand Abonnement door een Persoon bij deze Zorgaanbieder op (Notificaties over) deze Gegevensdienst | voor het wijzigen van de duur van een bestaand Abonnement door een Persoon bij deze Zorgaanbieder op (Notificaties over) deze Gegevensdienst | |||||
| 2b. | HTTP POST-request met structuur: <base url>/Subscription/ | HTTP PATCH-request met structuur: <base url>/Subscription/<subscription-id> | HTTP PATCH-request met structuur: <base url>/Subscription/<subscription-id> | |||||
| ||||||||
| 2c. | De OAuth Client gebruikt voor het sturen van het access token, voor alle subscription requests, de methode Authorization Request Header Field, zoals beschreven | |||||||
...
2. De subcription interface kent drie typen requests:
| subscription creation request | subscription duration request | subscription duration request | |||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2a. | voor het aanmaken van een nieuw Abonnement door een Persoon bij een Zorgaanbieder op (Notificaties over) deze Gegevensdienst | voor het wijzigen van de duur van een bestaand Abonnement door een Persoon bij deze Zorgaanbieder op (Notificaties over) deze Gegevensdienst | voor het wijzigen van de duur van een bestaand Abonnement door een Persoon bij deze Zorgaanbieder op (Notificaties over) deze Gegevensdienst | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 2b. | HTTP POST-request met structuur: <base url>/Subscription/ | HTTP PATCH-request met structuur: <base url>/Subscription/<subscription-id> | HTTP PATCH-request met structuur: <base url>/Subscription/<subscription-id> | ||||||||||||||||||||||||||||||||||||||||||||||||||
| Info | ||
|---|---|---|
| ||
Met de subscription creation request biedt de PGO Server aan de Subscription Server een nieuwe Subscription-resource aan, die het Abonnement representeert, met daaraan verbonden het vooralsnog eenzijdige akkoord van de Persoon. Hij verzoekt daarmee bovendien om een subscription response, waarmee ook het akkoord van de Zorgaanbieder is verbonden. Zo ontstaat de overeenkomst. Ook het aanpassen van de duur, via de einddatum parameter, van het Abonnement, door het versturen van een subscription duration request, ontvangt zo het akkoord van beide partijen; al mag de Zorgaanbieder een verkorting van het Abonnement niet weigeren; een verlenging kan wel geweigerd worden door de Zorgaanbieder. Een verkorting of beëindiging van een Abonnement, door het versturen van een subscription duration request respectievelijk een subscription termination request, is een eenzijdige aanpassing dan wel opzegging van de overeenkomst. De Zorgaanbieder mag deze niet weigeren en er is in die zin geen sprake van een akkoord van beide partijen. |
Authorization Request Header Field, zoals beschreven in sectie 2.1 van RFC6750.| Info |
|---|
| De methode Authorization Request Header Field biedt de beste beveiliging. |
3a. De subscription creation request:
- in de url MOGEN GEEN parameters worden meegeven
- bevat een complete representatie van de Subscription Resource met de volgende parameters:
| parameter | vulling | toelichting |
|---|---|---|
| verplicht, dezelfde waarde als voor de Zorgaanbieder in de scope van het gebruikte access token | - |
| verplicht, dezelfde waarde als voor de Gegevensdienst in de scope van het gebruikte access token | - |
client_id | verplicht, dezelfde waarde als de client_id die gebruikt is in het gebruikte access token | - |
| verplicht, de waarde voor de gewenste dag waarop het Abonnement stopt. | De De Subscription Server controleert of de
|
3b. De subscription duration request:
- MOET in de url de correcte
subscription-idmeegeven - bevat alleen de volgende parameters:
| parameter | vulling | toelichting |
|---|---|---|
end_date | verplicht, datum waarop het Abonnement verloopt. | De De Subscription Server controleert of de
|
| Info |
|---|
Met de subscription duration request verzoekt de PGO Server aan de Subscription Server de duur van een Abonnement aan te passen. Daarbij geeft de PGO Server bovendien alvast aan dat deze wijziging de goedkeuring van de Persoon heeft. Een Zorgaanbieder mag de verlenging van een Abonnement weigeren; een verkorting moet worden gehonoreerd. |
3c. De subscription termination request:
- MOET in de url de correcte
subscription-idmeegeven - MOET GEEN andere parameters bevatten.
| Info |
|---|
| Info |
| De methode Authorization Request Header Field biedt de beste beveiliging. |
3a. De subscription creation request:
- in de url MOGEN GEEN parameters worden meegeven
- bevat een complete representatie van de Subscription Resource met de volgende parameters:
| parameter | vulling | toelichting |
|---|---|---|
| verplicht, dezelfde waarde als voor de Zorgaanbieder in de scope van het gebruikte access token | - |
| verplicht, dezelfde waarde als voor de Gegevensdienst in de scope van het gebruikte access token | - |
client_id | verplicht, dezelfde waarde als de client_id die gebruikt is in het gebruikte access token | - |
| verplicht, de waarde voor de gewenste dag waarop het Abonnement stopt. | De De Subscription Server controleert of de
|
3b. De subscription duration request:
- MOET in de url de correcte
subscription-idmeegeven - bevat alleen de volgende parameters:
| parameter | vulling | toelichting |
|---|---|---|
end_date | verplicht, datum waarop het Abonnement verloopt. | De De Subscription Server controleert of de
|
| Info |
|---|
Met de subscription duration request verzoekt de PGO Server aan de Subscription Server de duur van een Abonnement aan te passen. Daarbij geeft de PGO Server bovendien alvast aan dat deze wijziging de goedkeuring van de Persoon heeft. Een Zorgaanbieder mag de verlenging van een Abonnement weigeren; een verkorting moet worden gehonoreerd. |
3c. De subscription termination request:
- MOET in de url de correcte
subscription-idmeegeven - MOET GEEN andere parameters bevatten.
| Info |
|---|
Het access token moet een scope hebben die precies overeenkomt met de parameters van het betreffende subscription creation request of subscription duration request of subscription termination request en met het abonnement aangeduid met het subscription-id. Daarnaast geldt dat in het geval van een subscription creation request of subscription duration request de |
end_date) van het Abonnement in onder voorbehoud van het beleid van de Zorgaanbieder (zie 3c.) en de waarde van de maximale duur van de desbetreffende Gegevensdienst in de Catalogus. | Info | ||
|---|---|---|
| ||
De subscription server heeft zekere vrijheid om bij het verwerken van een request rekening te houden met tijdzone's en datumgrenzen bij het bepalen van de einddatum van een Abonnement. |
| Info | ||
|---|---|---|
| ||
Een Zorgaanbieder heeft zowel verantwoordelijkheden als vrijheidsgraden rond het aanbieden en aangaan van Abonnementen. In het Afsprakenstelsel wordt dit gefaciliteerd door de Zorgaanbieder de mogelijkheid te geven beleid te voeren rond Abonnement op Notificaties. Een Zorgaanbieder kan voor een bepaalde Gegevensdienst een eigen maximale duur (binnen die gesteld in de Catalogus) opgeven. Ook kan de Zorgaanbieder bijvoorbeeld bepalen of het aantal Abonnementen per Persoon per Gegevensdienst begrensd is tot een bepaald maximum. Een Zorgaanbieder mag het verlengen van een bestaand Abonnement weigeren. |
end_date) van het Abonnement in onder voorbehoud van het beleid van de Zorgaanbieder (zie 3c.) en de waarde van de maximale duur van de desbetreffende Gegevensdienst in de Catalogus. | Info | ||
|---|---|---|
| ||
De subscription server heeft zekere vrijheid om bij het verwerken van een request rekening te houden met tijdzone's en datumgrenzen bij het bepalen van de einddatum van een Abonnement. |
| Info | ||
|---|---|---|
| ||
Een Zorgaanbieder heeft zowel verantwoordelijkheden als vrijheidsgraden rond het aanbieden en aangaan van Abonnementen. In het Afsprakenstelsel wordt dit gefaciliteerd door de Zorgaanbieder de mogelijkheid te geven beleid te voeren rond Abonnement op Notificaties. Een Zorgaanbieder kan voor een bepaalde Gegevensdienst een eigen maximale duur (binnen die gesteld in de Catalogus) opgeven. Ook kan de Zorgaanbieder bijvoorbeeld bepalen of het aantal Abonnementen per Persoon per Gegevensdienst begrensd is tot een bepaald maximum. Een Zorgaanbieder mag het verlengen van een bestaand Abonnement weigeren. |
| Info | ||
|---|---|---|
| ||
Met de subscription response geeft de Subscription Server aan dat ook de Zorgaanbieder akkoord gaat met het Abonnement. |
5b. De parameters in de response op een subscription creation request worden als volgt gevuld:
| parameter | vulling | toelichting |
|---|---|---|
| verplicht, dezelfde waarde als voor de Gegevensdienst in het request | - |
client_id | verplicht, dezelfde waarde als de client_id die gebruikt is in het gebruikte access token | - |
end_date | datum waarop het Abonnement verloopt. | Deze datum geeft de dag aan waarop de Subscription Server stopt met het sturen van Notificaties voor dit Abonnement. Conform RFC 3339 full-date: 'YYYY-MM-DD' |
subscription_id | identificatie waarmee de Subscription Server het Abonnement uniek voor deze Persoon en de Dienstverlener persoon identificeert | Deze waarde gebruikt de Subscription Server om bij een binnenkomende Subscription Creation Request of Subscription Duration Request het betreffende Abonnement te identificeren. Ook identificeert dit het Abonnement in logbestanden. Het |
5c. De parameters in de response op een subscription duration request worden als volgt gevuld:
| parameter | vulling | toelichting |
|---|---|---|
end_date | datum waarop het Abonnement verloopt. | Deze datum geeft de dag aan waarop de Subscription Server stopt met het sturen van Notificaties voor dit Abonnement. Conform RFC 3339 full-date: 'YYYY-MM-DD' |
| Info | ||
|---|---|---|
| ||
De Subscription Server heeft enige vrijheid bij het hanteren van het precieze moment op de dag waarop gestopt wordt met het versturen van Notificaties. Het staat de Subscription Server vrij om dit op enig moment van de betreffende dag te doen. Bij het verlopen van het Abonnement verstuurt de Subscription Server een subscription notification naar de client van de Persoon. |
...
| 5a. De http status van de subscription response wordt gezet op 201 na het succesvol aanmaken van het Abonnement. | 5a. De http status van de subscription response wordt gezet op 200 na het succesvol bijwerken van het Abonnement. | 5a. De http status van de subscription response wordt gezet op 204 na het succesvol verwijderen van het Abonnement. | |||||||||||||||||||||
| |||||||||||||||||||||||
5b. De parameters in de response op een subscription creation request worden als volgt gevuld:
| 5c. De parameters in de response op een subscription duration request worden als volgt gevuld:
| 5d. De response op een subscription termination request mag geen parameters bevatten. | |||||||||||||||||||||
| |||||||||||||||||||||||
6. Na ontvangst van een subscription creation request of een subscription duration request of een subscription termination request , in UCI Abonneren, zal de Subscription Server, indien in antwoord daarop een subscription response dient te worden gedaan, na maximaal zestig (60) seconden dit subscription response ter beschikking stellen aan de PGO Server. Dit gedrag van de Subscription Server is gedurende minimaal 98,5% van de tijd beschikbaar.
7. Voor zover er in het verkeer tussen PGO Server en Subscription Server in UCI Abonneren sprake is, in de stuurgegevens, van een gegevenselement dat tot de identiteit van de Zorggebruiker herleid kan worden, gebruiken zij daarvoor niets anders dan de OAuth-gegevens die zij in hun respectievelijke OAuth Client en OAuth Resource Server moeten uitwisselen. PGO Server, Authorization Server en Subscription Server treffen goed beveiligde voorzieningen waarmee zij hieruit waar nodig zelf de identiteit van de Zorggebruiker kunnen vaststellen.
| Info |
|---|
| Toelichting Met het oog op het borgen van de privacy en het zo eenvoudig mogelijk houden van de architectuur van het MedMij Afsprakenstelsel, wordt ervoor gekozen de identifier voor de Zorggebruiker onderweg zo betekenisloos mogelijk te houden. Alle betekenis wordt er ter weerszijden aan verbonden door raadpleging van interne registraties. Omdat de PGO Server, Authorization Server en Subscription Server samen een OAuth-flow afhandelen, beschikken zij (na authenticatie van de Zorggebruiker) over tokens die de identiteit van de Zorggebruiker vertegenwoordigen, namelijk (eerst) de authorization code en (later) het access token. Buiten deze hoeven en mogen er geen identificerende gegevenselementen in het verkeer worden opgenomen. |
8. OAuth Resource Server en OAuth Client handelen uitzonderingssituaties inzake het subscription interface af volgens onderstaande tabel.
Nummer | Implementeert uitzondering | Uitzondering | Actie | Melding | Vervolg |
|---|---|---|---|---|---|
| Subscription interface 1 | UC Abonneren 6 | De validatie van het access token door Subscription Server faalt, of er wordt niet voldaan aan de beschikbaarheidsvoorwaarde. Zie ook de toelichting op Beschikbaarheids- en ontvankelijkheidsvoorwaarde. | Subscription Server informeert PGO Server over deze uitzondering. PGO Server informeert daarop Zorggebruiker hierover. | Conform HTTP specificatie met status code 401 "Niet geautoriseerd" | Allen stoppen de flow onmiddellijk na geïnformeerd te zijn over de uitzondering. |
| Subscription interface 2 | Subscription Server ontvangt een ongeldig verzoek. | Conform HTTP specificatie met status code 400 "Foute aanvraag" | |||
| Subscription interface 3 | UC Abonneren 3 | Subscription Server kan in de request niet, niet geheel of niet tijdig uitvoeren, om redenen anders dan uitzondering Subscription interface 1, 2, 4 of 5. | Conform HTTP specificatie met met status code 500 "Interne serverfout" | ||
| Subscription interface 4 | UC Abonneren 7 | Subscription Server ontvangt een correct verzoek dat op basis van door de Zorgaanbieder ingesteld beleid geweigerd wordt. | Conform HTTP specificatie met status code 422 "Aanvraag kan niet verwerkt worden" | ||
| Subscription interface 5 | UC Abonneren 8 | Subscription Server ontvangt een correct verzoek dat verwijst naar een niet bestaand Abonnement (subscription-id). | Conform HTTP specificatie met status code 405 "Methode niet toegestaan" |