Merge pull request #113 from NHSDigital/docs/NPA-3887_Document_Relation_Person_Sandbox_Scenarios_rebased

NPA-3887 Document Sandbox Responses

Author: JackPlowman

.gitignore

@@ -19,3 +19,8 @@ smoketest-report.xml
 env
 .dir-locals.el
 *.pyc
+
+sandbox/output.json
+sandbox/pytest_html_report.html
+sandbox/archive/
+sandbox/.hypothesis/

sandbox/api/app.py

@@ -18,6 +18,7 @@
     check_for_validate,
     generate_response,
     load_json_file,
+    remove_system,
 )
 
 app = Flask(__name__)
@@ -50,8 +51,8 @@ def get_related_persons() -> Union[dict, tuple]:
         if errors := check_for_errors(request):
             return errors
 
-        identifier = request.args.get("identifier")
-        patient_identifier = request.args.get("patient:identifier")
+        identifier = remove_system(request.args.get("identifier"))
+        patient_identifier = remove_system(request.args.get("patient:identifier"))
         include = request.args.get("_include")
 
         if empty := check_for_empty(identifier, patient_identifier):

…rson/bad_request_missing_parameters.json …rson/bad_request_identifier_invalid.jsonsandbox/api/responses/GET_RelatedPerson/bad_request_missing_parameters.json renamed to sandbox/api/responses/GET_RelatedPerson/bad_request_identifier_invalid.json sandbox/api/responses/GET_RelatedPerson/bad_request_missing_parameters.json renamed to sandbox/api/responses/GET_RelatedPerson/bad_request_identifier_invalid.json

@@ -1,18 +1,18 @@
 {
   "issue": [
     {
-      "code": "exception",
+      "code": "invalid",
       "details": {
         "coding": [
           {
-            "code": "BAD_REQUEST",
-            "display": "Required parameter(s) are missing.",
+            "code": "INVALID_IDENTIFIER_VALUE",
+            "display": "Provided value is invalid",
             "system": "https://fhir.nhs.uk/R4/CodeSystem/ValidatedRelationships-ErrorOrWarningCode",
             "version": "1"
           }
         ]
       },
-      "diagnostics": "Invalid request with error - One or more required parameters are missing.",
+      "diagnostics": "Not a valid NHS Number provided for the 'identifier' parameter",
       "severity": "error"
     }
   ],

…_request_identifier_not_as_expected.json …d_request_identifier_invalid_system.jsonsandbox/api/responses/GET_RelatedPerson/bad_request_identifier_not_as_expected.json renamed to sandbox/api/responses/GET_RelatedPerson/bad_request_identifier_invalid_system.json sandbox/api/responses/GET_RelatedPerson/bad_request_identifier_not_as_expected.json renamed to sandbox/api/responses/GET_RelatedPerson/bad_request_identifier_invalid_system.json

@@ -32,7 +32,12 @@ def test_get_response(mock_open: MagicMock) -> None:
         ),
         (
             "identifier=123456789",  # identifier length is less than 10
-            "./api/responses/GET_RelatedPerson/bad_request_identifier_not_as_expected.json",
+            "./api/responses/GET_RelatedPerson/bad_request_identifier_invalid.json",
+            400,
+        ),
+        (
+            "identifier=https://fhir.nhs.uk/ID/nhs-number|1234567890",  # identifier system invalid
+            "./api/responses/GET_RelatedPerson/bad_request_identifier_invalid_system.json",
             400,
         ),
     ],

sandbox/api/tests/test_utils.py

@@ -1,5 +1,5 @@
 from json import load, dumps
-from typing import Optional
+from typing import Optional, Any
 
 from flask import request, Response
 
@@ -49,17 +49,33 @@ def check_for_errors(request: request) -> Optional[tuple]:
     Returns:
         Optional[tuple]: Tuple with response and status code if error is found
     """
-    if not request.args.get("identifier"):
+    identifier = request.args.get("identifier")
+    identifier_without_system = remove_system(request.args.get("identifier"))
+
+    if not identifier:
         return (
             load_json_file(
                 "./api/responses/GET_RelatedPerson/bad_request_identifier_missing.json"
             ),
             400,
         )
-    elif request.args.get("identifier") and len(request.args.get("identifier")) != 10:
+    elif identifier and len(identifier_without_system) != 10:
+        # invalid identifier
+        return (
+            load_json_file(
+                "./api/responses/GET_RelatedPerson/bad_request_identifier_invalid.json"
+            ),
+            400,
+        )
+    elif (
+        isinstance(identifier, str)
+        and "|" in identifier
+        and "https://fhir.nhs.uk/Id/nhs-number" != identifier.split("|", maxsplit=2)[0]
+    ):
+        # invalid identifier system
         return (
             load_json_file(
-                "./api/responses/GET_RelatedPerson/bad_request_identifier_not_as_expected.json"
+                "./api/responses/GET_RelatedPerson/bad_request_identifier_invalid_system.json"
             ),
             400,
         )
@@ -91,8 +107,8 @@ def check_for_validate(
     identifier: str,
     patient_identifier: str,
     include: str,
-    basefile: str,
-    incfile: str,
+    base_file: str,
+    inc_file: str,
 ) -> Response:
     """Checks for validate request responses for a given relationship record
 
@@ -101,41 +117,41 @@ def check_for_validate(
         identifier (str): The identifier supplied to the request
         patient_identifier (str): The patient:identifier supplied to the request
         include (str): The include parameter supplied to the request
-        basefile (str): The file to return when record matches but does not request includeded data
-        incfile (str): The file to return when record matches and does request included data
+        base_file (str): The file to return when record matches but does not request included data
+        inc_file (str): The file to return when record matches and does request included data
 
     Returns:
         Response: Resultant response or None
     """
     if identifier and patient_identifier == value and include == INCLUDE_FLAG:
         # Request with identifier, patient and _include=patient
-        return generate_response(load_json_file(incfile))
+        return generate_response(load_json_file(inc_file))
     elif identifier and patient_identifier == value:
         # Request with identifier and patient
-        return generate_response(load_json_file(basefile))
+        return generate_response(load_json_file(base_file))
 
 
 def check_for_list(
-    value: str, identifier: str, include: str, basefile: str, incfile: str
+    value: str, identifier: str, include: str, base_file: str, inc_file: str
 ) -> Response:
     """Check for a list relationship response for a given NHS number
 
     Args:
         value (str): NHS number of the relationship to look for
         identifier (str): The identifier supplied to the request
         include (str): The include parameter supplied to the request
-        basefile (str): The file to return when record matches but does not request includeded data
-        incfile (str): The file to return when record matches and does request included data
+        base_file (str): The file to return when record matches but does not request included data
+        inc_file (str): The file to return when record matches and does request included data
 
     Returns:
         Response: Resultant response or None
     """
     if identifier == value and include == INCLUDE_FLAG:
         # Request with identifier and _include=patient
-        return generate_response(load_json_file(incfile))
+        return generate_response(load_json_file(inc_file))
     elif identifier:
         # Request with identifier
-        return generate_response(load_json_file(basefile))
+        return generate_response(load_json_file(base_file))
 
 
 def generate_response(content: str, status: int = 200):
@@ -149,3 +165,12 @@ def generate_response(content: str, status: int = 200):
         Response: Resultant Response object based on input.
     """
     return Response(dumps(content), status=status, mimetype="application/fhir+json")
+
+
+def remove_system(identifier: Any) -> str:
+    if isinstance(identifier, str):
+        if "|" in identifier:
+            # Identifier includes system
+            return identifier.split("|", maxsplit=1)[1]
+        return identifier
+    return ""

sandbox/api/utils.py

@@ -162,7 +162,15 @@ paths:
 
         ## Sandbox test scenarios
 
-        For details of sandbox test scenarios, or to try out the sandbox using our 'Try it out' feature, see the documentation for each endpoint.
+        | Scenario        | Request                                         | Response                         |
+        | --------------- | ----------------------------------------------- | -------------------------------- |
+        | Example request | Example questionnaire response from try it now  | HTTP Status 200 Success response |
+
+        ### Sandbox constraints
+          - Questionnaire Response is not validated.
+          - Headers are not tested. `X-Request-ID` and `X-Correlation-ID` are disregarded.
+
+        Or perhaps you'd like to try out the sandbox using our 'Try it out' feature.
 
       operationId: new-access-request
       parameters:
@@ -253,7 +261,25 @@ paths:
 
         ## Sandbox test scenarios
 
-        For details of sandbox test scenarios, or to try out the sandbox using our 'Try it out' feature, see the documentation for each endpoint.
+        | Scenario                                                                    | Request                                                                                                | Response                                                                                       |
+        | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+        | List Relationship                                                           | `identifier`=`9000000017`                                                                              | HTTP Status 200 List of relationships for the proxy                                            |
+        | List Relationship and include patient's details                             | `identifier`=`9000000017` and `_include`=`RelatedPerson:patient`                                       | HTTP Status 200 List of relationships for the proxy and includes patient data                  |
+        | List Relationship and no relationships returned                             | `identifier`=`9000000033`                                                                              | HTTP Status 200 Empty bundle                                                                   |
+        | Verify Relationship between proxy and patient                               | `identifier`=`9000000017` and `patient:identifier`=`9000000009`                                        | HTTP Status 200 Verified relationship between patient and proxy                                |
+        | Verify Relationship between proxy and patient and include patient's details | `identifier`=`9000000017` and `patient:identifier`=`9000000009` and `_include`=`RelatedPerson:patient` | HTTP Status 200 Verified relationship between patient and proxy and includes patient's details |
+        | Verify Relationship between proxy and patient                               | `identifier`=`9000000017` and `patient:identifier`=`9000000025`                                        | HTTP Status 200 Verified relationship between patient and proxy                                |
+        | Verify Relationship between proxy and patient and include patient's details | `identifier`=`9000000017` and `patient:identifier`=`9000000025` and `_include`=`RelatedPerson:patient` | HTTP Status 200 Verified relationship between patient and proxy and includes patient's details |
+        | Missing identifier                                                          | `patient:identifier`=`9000000009`                                                                      | HTTP Status 400 and MISSING_IDENTIFIER_VALUE error response                                    |
+        | Invalid identifier                                                          | `identifier`=`900000000` Note: This identifier is 9 characters long, too short to be NHS Number        | HTTP Status 400 and INVALID_IDENTIFIER_VALUE error response                                    |
+        | Invalid identifier system                                                   | `identifier`=`https://fhir.nhs.uk/Id/nhs-number/9730675929`                                            | HTTP Status 400 and INVALID_IDENTIFIER_SYSTEM error response                                   |
+        | Identifier not supported in sandbox                                         | `identifier`=`1000000001`                                                                              | HTTP Status 404 and INVALIDATED_RESOURCE error response                                        |
+
+        ### Sandbox constraints
+          - Headers are not tested. `X-Request-ID` and `X-Correlation-ID` are disregarded.
+          - `patient:identifier` is not validated.
+
+        Or perhaps you'd like to try out the sandbox using our 'Try it out' feature.
 
       operationId: get-validated-relationships
       parameters:
@@ -1684,10 +1710,10 @@ components:
         format: token
       examples:
         withoutSystem:
-          value: 9000000009
+          value: 9000000017
           summary: NHS number specified without system.
         withSystem:
-          value: https://fhir.nhs.uk/Id/nhs-number|9000000009
+          value: https://fhir.nhs.uk/Id/nhs-number|9000000017
           summary: System and NHS number specified
 
     PatientIdentifier:
@@ -1701,10 +1727,10 @@ components:
         format: token
       examples:
         withoutSystem:
-          value: 9000000017
+          value: 9000000009
           summary: NHS number specified without system
         withSystem:
-          value: https://fhir.nhs.uk/Id/nhs-number|9000000017
+          value: https://fhir.nhs.uk/Id/nhs-number|9000000009
           summary: System and NHS number specified
 
     ConsentBundlePerformerIdentifier: