Merge pull request #110 from gematik/gematik/feature/api_design_rational

Add documentation to explain the api design rationale

Author: AlexanderGrossgematik

README.md

@@ -132,6 +132,10 @@ Wie oben erwähnt, wird das VSDM 2.0 auf die Verwendung einer RESTful FHIR-API r
 
 [vsdm2.yaml](./src/openapi/vsdm2.yaml).
 
+Zusätzliche Informationen zu Design-Entscheidungen und Abweichungen vom FHIR-Standard finden Sie hier:
+
+[API Design & FHIR-Konformität](docs/vsdm_api_design.md)
+
 
 
 # Kontakt

docs/vsdm_api_design.md

@@ -0,0 +1,19 @@
+# Design-Rationale und FHIR-Konformität
+
+Die VSDService-API verwendet einen von Standard-FHIR abweichenden Endpunkt-Ansatz:
+
+## Standard FHIR REST Pattern
+* `GET /fhir/Bundle/{id}` (Zugriff mit expliziter ID)
+* `GET /fhir/Bundle?identifier=...` (Suche nach Identifier)
+
+## VSDM2 Pattern
+* `GET /vsdservice/v1/vsdmbundle` (Fester Endpunkt ohne ID)
+
+## Begründung für diese Abweichung
+
+1. **Sicherheit:** Die KVNR erscheint nicht in der URL und wird daher nicht in Server-Logs oder Monitoring-Systemen erfasst.
+2. **Versorgungskontext-basiert:** Der Zugriff ist an den im PoPP-Token manifestierten Versorgungskontext gebunden. Die Identifikation erfolgt über die im PoPP-Token enthaltene KVNR.
+3. **Singleton-Semantik:** Pro authentifiziertem Versicherten existiert genau ein aktuelles VSDMBundle. Eine ID-basierte Adressierung ist nicht erforderlich.
+4. **Vereinfachung:** Clients müssen keine Resource-IDs konstruieren oder verwalten. Der Versorgungskontext bestimmt eindeutig, welches VSDMBundle zurückgegeben wird.
+
+Trotz dieser Abweichung vom Standard-FHIR-Pattern handelt es sich bei `/vsdservice/v1/vsdmbundle` um eine FHIR Resource (`VSDMBundle`) mit Standard-Resource-Semantik (ETag, If-None-Match, HTTP 304, etc.).

src/openapi/vsdm2.yaml

@@ -59,7 +59,21 @@ paths:
       tags:
         - Vsdm
       summary: Returns a VSDMBundle for the specified patient.
-      description: Returns a VSDMBundle with VSD about a specific patient that is addressed within the PoPP-Token in the request header.
+      description: |
+        Returns a VSDMBundle with VSD about a specific patient that is addressed within the PoPP-Token in the request header.
+        
+        **FHIR DEVIATION NOTICE:**
+        This endpoint deviates from standard FHIR REST patterns:
+        - Standard FHIR: GET /Bundle/{id}
+        - VSDM2: GET /vsdservice/v1/vsdmbundle (no ID in path)
+        
+        **Rationale:**
+        - Security: Patient KVNR is not exposed in URL
+        - Context-based: Patient identified via KVNR in PoPP token header
+        - Singleton: Exactly one current VSDMBundle per patient
+        
+        Despite this deviation, VSDMBundle remains a FHIR Resource with
+        standard resource semantics (ETag, conditional requests, etc.).
       operationId: getVSDMBundle
       security:
         - oAuthVsdm: [ vsdservice ]