Doc: describe RESTful transactions and endpoints

i4mi · Aug 7, 2023 · 7988dc1 · 7988dc1
1 parent 2025173
commit 7988dc1
Show file tree

Hide file tree

Showing 8 changed files with 413 additions and 56 deletions.
diff --git a/docs/endpoints.md b/docs/endpoints.md
@@ -1,14 +1,15 @@
 Here are the endpoints exposed by the MobileAccessGateway.
 
-| Transaction | URL                                                   |
-| ----------- | ----------------------------------------------------- |
-| ITI-65      | _instance_/fhir/                                      |
-| ITI-66      | _instance_/fhir/List                                  |
-| ITI-67      | _instance_/fhir/DocumentReference                     |
-| ITI-68      | _instance_/fhir/camel/xdsretrieve                     |
-| ITI-71      |                                                       |
-| ITI-78      | _instance_/fhir/Patient                               |
-| ITI-83      | _instance_/fhir/Patient/$ihe-pix                      |
-| ITI-93      |                                                       |
-| ITI-104     | _instance_/fhir/Patient                               |
-| PHARM-5     | _instance_/fhir/DocumentReference/$_{operation-name}_ |
+| Transaction          | URL                                                   |
+| -------------------- | ----------------------------------------------------- |
+| ITI-65               | _instance_/fhir/                                      |
+| ITI-66               | _instance_/fhir/List                                  |
+| ITI-67               | _instance_/fhir/DocumentReference                     |
+| ITI-68               | _instance_/camel/xdsretrieve                          |
+| ITI-71               | _instance_/camel/authorize                            |
+| ITI-78               | _instance_/fhir/Patient                               |
+| ITI-83               | _instance_/fhir/Patient/$ihe-pix                      |
+| ITI-93               |                                                       |
+| ITI-104              | _instance_/fhir/Patient                               |
+| PHARM-5              | _instance_/fhir/DocumentReference/$_{operation-name}_ |
+| Get X-User Assertion | _instance_/camel/assertion                            |
diff --git a/docs/features.md b/docs/features.md
@@ -10,3 +10,4 @@ The MobileAccessGateway provides translation from REST to SOAP variants of IHE t
 - ITI-93 to ITI-44
 - ITI-104 to ITI-44 or ITI-47
 - ITI-71 to ITI-40
+- RESTful Get X-User Assertion to Get X-User Assertion
diff --git a/docs/integration-primary-system.md b/docs/integration-primary-system.md
@@ -6,6 +6,7 @@ itself based on various IHE profiles.
 <svg width="20" height="20" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg"><path fill="#ffce31" d="M5.9 62c-3.3 0-4.8-2.4-3.3-5.3L29.3 4.2c1.5-2.9 3.9-2.9 5.4 0l26.7 52.5c1.5 2.9 0 5.3-3.3 5.3H5.9z"/><g fill="#231f20"><path d="m27.8 23.6l2.8 18.5c.3 1.8 2.6 1.8 2.9 0l2.7-18.5c.5-7.2-8.9-7.2-8.4 0"/><circle cx="32" cy="49.6" r="4.2"/></g></svg>
 Don't forget to properly encode the HTTP parameters in the queries (especially colons and pipes).
 In the following examples, they are shown decoded for a better readability.
+`Authorization` and `Accept` headers are not shown in the examples.
 
 <svg width="20" height="20" viewBox="0 0 48 48" xmlns="http://www.w3.org/2000/svg"><circle cx="24" cy="24" r="21" fill="#2196F3"/><path fill="#fff" d="M22 22h4v11h-4z"/><circle cx="24" cy="16.5" r="2.5" fill="#fff"/></svg>
 For HTTP GET requests, there is usually an equivalent HTTP POST request that should be supported.
@@ -15,11 +16,47 @@ For HTTP GET requests, there is usually an equivalent HTTP POST request that sho
 You should integrate one of the supported IDPs in your application.
 The SAML flow is the only one currently supported.
 
-In the REST transaction, the SAML assertion you got shall be [base64-url](https://datatracker.ietf.org/doc/html/rfc4648#section-5)
-encoded, prefixed with `Bearer ` and inserted in an `Authorization` HTTP header.
+Once you get the IDP SAML assertion, you can trade it for the community SAML assertion, which binds your IDP
+identification to a specific patient and a purpose of use.
+It is an HTTP POST request to `/assertion`, with the header `Scope` and the IDP SAML assertion as body.
+The header `Scope` contains the following values:
+
+- `purpose_of_use` (_[token][]_, required): a value from [EprPurposeOfUse](https://fhir.ch/ig/ch-epr-term/ValueSet-EprPurposeOfUse.html).
+- `subject_role` (_[token][]_, required): either `HCP`, `ASS`, `PAT` or `REP` in the system `urn:oid:2.16.756.5.30.1.127.3.10.6`.
+- `person_id` (_[string][]_, required): the patient EPR-SPID in the CX format.
+- `principal` (_[string][]_, only if role is ASS): the name of the healthcare professional an assistant is acting on
+  behalf of.
+- `principal_id` (_[token][]_, only if role is ASS): the GLN of the healthcare professional an assistant is acting on
+  behalf of.
+- `group` (_[string][]_, only if role is ASS): the name of the organization or group an assistant is acting on
+  behalf of.
+- `group_id` (_[token][]_, only if role is ASS): the OID of the organization or group an assistant is acting on
+  behalf of.
+
+```http title="Request"
+--8<-- "http_getxua.txt"
+```
+
+The response then looks like:
+
+```http title="Response"
+HTTP/1.1 200 OK
+Content-Type: application/json
 
-```http title="Example of request with authentication"
-GET / HTTP/1.1
+{
+  "access_token": "U0FNTGFzc2VydGlvbg",
+  "token_type": "IHE-SAML",
+  "expires_in": 60000,
+  "scope": "resourceId/761337610445502987 purposeOfUse/NORM role/HCP"
+}
+```
+
+The [base64-url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) encoded SAML assertion is given in
+`access_token`, and that value has to be prefixed with `Bearer ` and inserted in an `Authorization` HTTP header for
+all transactions that requires it.
+
+```http title="Example of request with the XUA"
+GET /... HTTP/1.1
 Authorization: Bearer U0FNTGFzc2VydGlvbg
 ```
 
@@ -103,35 +140,8 @@ If you want to add an identifier, you can put it in `identifier`.
 
 <details><summary>Examples</summary>
 
-```http
-PUT /Patient?identifier=urn:oid:2.16.756.5.30.1.196.3.2.1|MAGMED001 HTTP/1.1
-Content-Type: application/fhir+json
-
-{
-    "active": true,
-    "birthDate": "1987-10-08",
-    "gender": "male",
-    "id": "2.16.756.5.30.1.127.3.10.3-761337611735842172",
-    "identifier": [
-        {
-            "system": "urn:oid:2.16.756.5.30.1.196.3.2.1",
-            "value": "MAGMED001"
-        },
-        {
-            "system": "urn:oid:2.999.42",
-            "value": "new-identifier-value"
-        }
-    ],
-    "name": [
-        {
-            "family": "NEFF-WINGEIER",
-            "given": [
-                "Trong Sang"
-            ]
-        }
-    ],
-    "resourceType": "Patient"
-}
+```http title="Add an identifier"
+--8<-- "http_iti104.txt"
 ```
 
 </details>
@@ -165,6 +175,18 @@ GET /DocumentReference?patient.identifier=urn:oid:2.999|11111111&creation=ge2023
 
 You can also search for _SubmissionSets_ with the [ITI-66 (_Find Document Lists_) transaction](https://fhir.ch/ig/ch-epr-mhealth/iti-66.html).
 
+<details><summary>Examples</summary>
+
+```http title="Search all by patient identifier"
+GET /List?patient.identifier=urn:oid:2.999|11111111 HTTP/1.1
+```
+
+```http title="Search with additional parameters"
+GET /List?patient.identifier=urn:oid:2.999|11111111&code=submissionset&status=current&designationType=http://loinc.org|1234-5 HTTP/1.1
+```
+
+</details>
+
 ### Reading
 
 Retrieving a document is done with the [ITI-68 (_Retrieve Document_) transaction](https://fhir.ch/ig/ch-epr-mhealth/iti-68.html).
@@ -180,6 +202,10 @@ The transaction is an HTTP POST request to the endpoint `/`. The following profi
 
 <details><summary>Examples</summary>
 
+```http title="Publish a PDF file"
+--8<-- "http_iti65.txt"
+```
+
 </details>
 
 ## Professional and organization directory
@@ -252,17 +278,7 @@ See the [mapping from DICOM to FHIR](https://hl7.org/fhir/R4/auditevent-mappings
 <details><summary>Examples</summary>
 
 ```http
-POST /ARR/fhir/AuditEvent HTTP/1.1
-Content-Type: application/fhir+xml
-
-<Bundle>
-  <entry>
-    ...
-    <request>
-      <method value="POST"/>
-    </request>
-  </entry>
-</Bundle>
+--8<-- "http_iti20.txt"
 ```
 
 </details>

diff --git a/docs/snippets/http_getxua.txt b/docs/snippets/http_getxua.txt
@@ -0,0 +1,7 @@
+POST /assertion HTTP/1.1
+Scope: person_id=761337610445502987^^^&2.16.756.5.30.1.127.3.10.3&ISO purpose_of_use=urn:oid:2.16.756.5.30.1.127.3.10.5|NORM subject_role=urn:oid:2.16.756.5.30.1.127.3.10.6|HCP
+Content-Type: application/xml
+
+<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0">
+  <!-- Content of the IDP assertion… -->
+</saml2:Assertion>
diff --git a/docs/snippets/http_iti104.txt b/docs/snippets/http_iti104.txt
@@ -0,0 +1,28 @@
+PUT /Patient?identifier=urn:oid:2.16.756.5.30.1.196.3.2.1|MAGMED001 HTTP/1.1
+Content-Type: application/fhir+json
+
+{
+    "active": true,
+    "birthDate": "1987-10-08",
+    "gender": "male",
+    "id": "2.16.756.5.30.1.127.3.10.3-761337611735842172",
+    "identifier": [
+        {
+            "system": "urn:oid:2.16.756.5.30.1.196.3.2.1",
+            "value": "MAGMED001"
+        },
+        {
+            "system": "urn:oid:2.999.42",
+            "value": "new-identifier-value"
+        }
+    ],
+    "name": [
+        {
+            "family": "NEFF-WINGEIER",
+            "given": [
+                "Trong Sang"
+            ]
+        }
+    ],
+    "resourceType": "Patient"
+}
diff --git a/docs/snippets/http_iti20.txt b/docs/snippets/http_iti20.txt
@@ -0,0 +1,11 @@
+POST /ARR/fhir/AuditEvent HTTP/1.1
+Content-Type: application/fhir+xml
+
+<Bundle>
+  <entry>
+    ...
+    <request>
+      <method value="POST"/>
+    </request>
+  </entry>
+</Bundle>