Het subscription interface hoort bij de hoofdfunctie Regie.
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 DVP 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 Aanbieder 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 Aanbieder een verkorting van het Abonnement niet weigeren; een verlenging kan wel geweigerd worden door de Aanbieder.
Een beëindiging van een Abonnement, door het versturen van een subscription termination request, is een eenzijdige opzegging van de overeenkomst. De Aanbieder mag deze niet weigeren en er is in die zin geen sprake van een akkoord van beide partijen.
| 1. | De OAuth Client en de Subscription Server maken op de subscription interface gebruik van HTTP 1.1.
| |
| 2. | 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
| |
| 3. | 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. | |
| 4. | 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 |
|---|
aanbieder
| verplicht, dezelfde waarde als voor de Aanbieder in de scope van het gebruikte access token | - | gegevensdienst
| 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 | - | end_date
| verplicht, de waarde voor de gewenste dag waarop het Abonnement stopt. | De end_date dient gespecificeerd conform RFC 3339 full-date: 'YYYY-MM-DD' De Subscription Server controleert of de end_date geldig is, dit is als: |
| |
| 5. | 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 | | 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 subscription_id kan een integer waarde zijn, of een UUID, maar kan ook volgens een ander geldig identificatiepatroon worden gevuld. | zorgaanbieder | verplicht, dezelfde waarde als voor de Aanbieder in het request | - | gegevensdienst
| 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' |
| |
| 6. | 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 |
|---|
end_date | verplicht, datum waarop het Abonnement verloopt. | De end_date dient gespecificeerd conform RFC 3339 full-date: 'YYYY-MM-DD' De Subscription Server controleert of de end_date geldig is, dit is als: - de end_date valt binnen de huidige datum + de waarde van
duur in het gebruikte access token (zie (MedMij Afsprakenstelsel 2.0.3) Token interface ) - de end_date valt binnen de gestelde maximale
duur van een Abonnement - de end_date heeft een hogere waarde dan de huidige datum
|
| |
| 7. | 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. | |
| 8. | 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' |
| |
| 9. | 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
| |
| 10. | 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. | |
| 11. | Een response op een succesvol verwerkt termination creation request:- bevat een status code met waarde 204
- bevat in de HTTP body geen parameters
| |
| 12. | 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 Aanbieder 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 Aanbieder 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. Toelichting Een Aanbieder heeft zowel verantwoordelijkheden als vrijheidsgraden rond het aanbieden en aangaan van Abonnementen. In het Afsprakenstelsel wordt dit gefaciliteerd door de Aanbieder de mogelijkheid te geven beleid te voeren rond Abonnement op Notificaties. Een Aanbieder kan voor een bepaalde Gegevensdienst een eigen maximale duur (binnen die gesteld in de Catalogus) opgeven. Een Aanbieder 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. | |
| 13. | Indien bij het verwerken van een subscription request aan alle voorwaarden is voldaan, dan Toelichting 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. | |
| 14. | Bij het verlopen van het Abonnement verstuurt de Subscription Server een subscription notification naar de client van de Persoon. | |
| 15. | Na ontvangst van een subscription request , in de functie 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 DVP Server. Dit gedrag van de Subscription Server is gedurende minimaal 98,5% van de tijd beschikbaar. | |
| 16. | Voor zover er in het verkeer tussen DVP Server en Subscription Server in de functie Abonneren sprake is, in de stuurgegevens, van een gegevenselement dat tot de identiteit van de Persoon 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. DVP Server, Authorization Server en Subscription Server treffen goed beveiligde voorzieningen waarmee zij hieruit waar nodig zelf de identiteit van de Persoon kunnen vaststellen. 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 Persoon onderweg zo betekenisloos mogelijk te houden. Alle betekenis wordt er ter weerszijden aan verbonden door raadpleging van interne registraties. Omdat de DVP Server, Authorization Server en Subscription Server samen een OAuth-flow afhandelen, beschikken zij (na authenticatie van de Persoon) over tokens die de identiteit van de Persoon 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. | |
| 17. | 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 | Abonneren 3 | Het subscription request bevat geen access_token. | Subscription Server informeert DVP Server over deze uitzondering. | Een Status-Code 401 conform HTTP specificatie. In deze situatie retourneert de Subscription Server uitdrukkelijk géén nadere informatie over de opgetreden uitzondering. | DVP Server informeert daarop Persoon over deze uitzondering. Na afhandeling van de in deze tabel benoemde informatiestappen, stoppen allen de onmiddellijk met de flow. | | Subscription interface 2 | De Subscription Server detecteert dat het meegezonden access_token is verlopen of om een andere reden niet geldig is. | Een Status-Code 401 conform HTTP specificatie en een WWW-Authenticate HTTP response header met als auth-scheme "Bearer" en een error attribuut met waarde "invalid_token". conform RFC 6750. | | Subscription interface 3 | De Subscription Server detecteert dat de scope die is verbonden aan het meegezonden access_token niet toereikend voor de uitvoering van het subscription request. | Een Status-Code 403 conform HTTP specificatie en een WWW-Authenticate HTTP response header met als auth-scheme "Bearer" en een error attribuut met waarde "insufficient_scope". conform RFC 6750. | | Subscription interface 4 | Het subscription request mist een vereiste (header) parameter, bevat een niet-ondersteunde (header) parameter of parameterwaarde, gebruikt meer dan één methode voor het doorgeven van een access_token, of is op een andere wijze misvormd. | Een Status-Code 400 conform HTTP specificatie en een WWW-Authenticate HTTP response header met als auth-scheme "Bearer" en een error attribuut met waarde "invalid_request". conform RFC 6750. | | Subscription interface 5 | De Subscription Server detecteert dat niet kan worden voldaan aan de beschikbaarheidsvoorwaarde. Zie ook de toelichting op Beschikbaarheids- en ontvankelijkheidsvoorwaarde. | Een Status-Code 403 conform HTTP specificatie en een WWW-Authenticate HTTP response header met als auth-scheme "Bearer" en een error attribuut met waarde "access_denied". conform RFC 6750. Het vereiste error attribuut is bewust in lijn gebracht met het gedrag van de Authorization Server bij deze uitzonderingssituatie. | | Subscription interface 6 | Subscription Server ontvangt een correct verzoek dat op basis van door de Aanbieder ingesteld beleid geweigerd wordt. | Een Status-Code 422 "Aanvraag kan niet verwerkt worden" conform HTTP specificatie. | | Subscription interface 7 | Subscription Server ontvangt een correct verzoek dat echter verwijst naar een niet bestaand Abonnement (subscription-id). | Een Status-Code 404 "Niet gevonden" conform HTTP specificatie. | | Subscription interface 8 | Subscription Server kan in de request niet, niet geheel of niet tijdig voorzien, om redenen anders dan in bovengenoemde uitzonderingen. | Een toepasselijke Status-Code conform HTTP specificatie. |
| |
