Subscription interface
- Ron van Holland (Unlicensed)
Inleiding
Op deze pagina staan alleen de verantwoordelijkheden inzake het subscription interface die nog niet genoemd staan in:
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 OAuth Client (PGO Server) verstuurt de subscription request middels een HTTP POST van een Subscription resource op het beoogde Subscription Endpoint. De OAuth Client en de OAuth Resource Server (Subscription Server) maken voor het uitwisselen van requests en responses gebruik van JSON.
3. De parameters in de subscription request worden als volgt gevuld:
parameter | vulling | toelichting |
|---|---|---|
|
| Slechts aanwezig en gevuld bij een verzoek om een Abonnement bij te werken met een nieuwe einddatum en -tijd, en bij een verzoek om een Abonnement te beëindigen. Het |
|
| Slechts optioneel aanwezig en gevuld bij een verzoek om een Abonnement aan te gaan, of een Abonnement bij te werken met een nieuwe einddatum en -tijd. Wanneer De tijd dient tenminste op de seconde nauwkeurig te worden gespecificeerd en dient ook informatie omtrent de geldende tijdzone te bevatten. Een Abonnement wordt door de Subscription Server op de einddatum automatisch verwijderd. |
| letterlijke waarde | Slechts aanwezig en gevuld bij een verzoek om een Abonnement te beëindigen. |
4. De parameters in de subscription response worden als volgt gevuld:
parameter | vulling | toelichting |
|---|---|---|
|
| Slechts aanwezig en gevuld bij een antwoord op een verzoek om een Abonnement aan te gaan en bij een antwoord op een verzoek om een Abonnement bij te werken met een nieuwe einddatum en -tijd. Het |
|
| Slechts aanwezig en gevuld bij een antwoord op een verzoek om een Abonnement aan te gaan en bij een antwoord op een verzoek om een Abonnement bij te werken met een nieuwe einddatum en -tijd. Wanneer een geldige einddatum- en tijd is gespecificeerd in het subscription request, dan dient deze te worden gehonoreerd. De tijd dient tenminste op de seconde nauwkeurig te worden gespecificeerd en dient ook informatie omtrent de geldende tijdzone te bevatten. |
| letterlijke waarde | Slechts aanwezig en gevuld bij een antwoord op een verzoek om een Abonnement aan te gaan en bij een antwoord op een verzoek om een Abonnement bij te werken met een nieuwe einddatum en -tijd. |
5. De maximaal toegestane abonnementsduur bedraagt 365 dagen.
Toelichting
Voorbeeld van een subscription request en subscription response voor het aangaan van een nieuw Abonnement:
| subscription request | subscription response |
|---|---|
POST /Subscription HTTP/1.1 { "end" : "2021-01-15T14:30:00Z" } | HTTP/1.1 201 Created { "id" : "496749327x", } |
Voorbeeld van een subscription request en subscription response voor het bijwerken van een Abonnement met een nieuwe einddatum en -tijd:
POST /Subscription HTTP/1.1 { "id" : "496749327x", } | HTTP/1.1 200 OK { "id" : "496749327x", } |
Voorbeeld van een subscription request en subscription response voor het beëindigen van een bestaand Abonnement:
| subscription request | subscription response |
|---|---|
POST /Subscription HTTP/1.1 { "id" : "496749327x", } | HTTP/1.1 200 OK |
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 zullen 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 of uitzondering Subscription interface 2. | Conform HTTP specificatie met met status code 500 "Interne serverfout" |