Subscription interface 1.3.0
=== Nieuwe tekst ter vervanging van de huidige pagina ===
Inleiding
Het subscription interface hoort bij de /wiki/spaces/MedMijAfsprakenstelsel120/pages/135103542.
Er zijn drie typen subscription request:
- de subscription creation request voor het aanmaken van een nieuw Abonnement;
- de subscription modification request voor het wijzigen van de duur van een bestaand Abonnement;
- de subscription termination request voor het beëindigen van een bestaand Abonnement.
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 modification 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 beëindiging van een Abonnement, door het versturen van een subscription termination request, is een eenzijdige opzegging van de overeenkomst. De Zorgaanbieder mag deze niet weigeren en er is in die zin geen sprake van een akkoord van beide partijen.
1a. De OAuth Client en de Subscription Server maken op de subscription interface gebruik van HTTP 1.1.
1b. De OAuth Client en de Subscription Server maken voor het uitwisselen van subscription requests en de bijbehorende responses gebruik van het formaat JSON. Dit wordt in de HTTP header aangegeven middels:
- Content-Type: application/json
- Accept: application/json
1c. De OAuth Client gebruikt voor het sturen van het access token, voor alle typen subscription request, de methode Authorization Request Header Field, zoals beschreven in sectie 2.1 van RFC6750.
Toelichting
De methode Authorization Request Header Field biedt de beste beveiliging.
Het access token moet een scope hebben die precies overeenkomt met de parameters van het betreffende subscription request en bij wijzen of beëindigen van een Abonnement ook met de zorgaanbieder en gegevensdienst van het betreffende Abonnement dat wordt aangeduid met het subscription_id.
2a. De subscription creation request:
- is een HTTP POST-request met structuur:
<base url>/Subscription/en verder zonder parameters in de URL - bevat in de HTTP body 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
|
2b. Een response op een succesvol verwerkt subscription creation request:
- bevat een status code met waarde 201
- bevat een location header bevatten met een link naar de nieuwe resource (inclusief de toegekende subscription-id):
<base url>/Subscription/<subscription-id> - bevat in de HTTP body de volgende parameters:
parameter | vulling | toelichting |
|---|---|---|
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 modification Request het betreffende Abonnement te identificeren. Ook identificeert dit het Abonnement in logbestanden. Het |
zorgaanbieder | verplicht, dezelfde waarde als voor de Zorgaanbieder in het request | - |
| 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' |
3a. De subscription modification request:
- is een HTTP PATCH-request met structuur:
<base url>/Subscription/<subscription-id>en verder zonder parameters in de URL - bevat in de HTTP body slechts de volgende parameters van de aan te passen Subscription Resource:
parameter | vulling | toelichting |
|---|---|---|
| verplicht, datum waarop het Abonnement verloopt. | De De Subscription Server controleert of de
|
3b. In het geval van een subscription modification request verifieert de Subscription Server dat voor het meegegeven subscription-id een geldig Abonnement is geregistreerd, waarvan de waarden van de attributen overeenkomen met de parameters in de scope van het gebruikte access token. Indien dit niet het geval is, behandelt de Subscription Server dat als uitzondering Subscription interface 4.
3c. Een response op een succesvol verwerkt modification creation request:
- bevat een status code met waarde 200
- bevat in de HTTP body de volgende parameters:
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' |
4a. De subscription termination request:
- is een HTTP DELETE-request met structuur:
<base url>/Subscription/<subscription-id>en verder zonder parameters in de URL - bevat in de HTTP body geen parameters
4b. In het geval van een subscription termination request verifieert de Subscription Server dat voor het meegegeven subscription-id een geldig Abonnement is geregistreerd, waarvan de waarden van de attributen overeenkomen met de parameters in de scope van het gebruikte access token. Indien dit niet het geval is, behandelt de Subscription Server dat als uitzondering Subscription interface 4.
4c. Een response op een succesvol verwerkt termination creation request:
- bevat een status code met waarde 204
- bevat in de HTTP body geen parameters
5a. In het geval van een subscription creation request of een subscription modification request stelt de Subscription Server stelt de einddatum (end_date) van het Abonnement in onder voorbehoud van het beleid van de Zorgaanbieder en de waarde van de maximale duur van de desbetreffende Gegevensdienst in de Catalogus. Op grond hiervan mag de Subscription Server een subscription request toetsen aan het beleid dat de Zorgaanbieder voert voor Abonnementen op de Gegevensdienst en een request op grond hiervan een kortere duur toekennen of weigeren. In geval van weigering behandelt de Subscription Server dit als uitzondering Subscription interface 5.
Beleid omtrent Abonnementen
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. Een Zorgaanbieder mag het verlengen van een bestaand Abonnement weigeren.
De subscription server heeft zekere vrijheid om bij het bepalen van de einddatum van een Abonnement rekening te houden met tijdzone's en datumgrenzen.
5b. Indien bij het verwerken van een subscription request aan alle voorwaarden is voldaan, dan
- laat de Subscription Server het Abonnement per direct ingaan, danwel
- beëindigd de Subscription Server het Abonnement per direct.
Einddatum en tijd
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.
6. Na ontvangst van een subscription 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.
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 404 "Niet gevonden" |