[ERSSUP-61674]-[JW/AO]-[Retrieve Binary R4 API design]-[FV]

Author: francisco-videira-nhs

sandbox/src/routes/index.js

@@ -42,6 +42,8 @@ const retrieveHealthcareService = require('./r4/retrieveHealthcareService')
 const searchForHealthcareServices = require('./r4/searchForHealthcareServices')
 const searchServiceRequest = require('./r4/searchServiceRequest')
 const requestUploadUri = require('./r4/requestUploadUri')
+const retrieveBinary = require('./r4/retrieveBinary')
+const retrieveBinaryHelper = require('./r4/retrieveBinaryHelper')
 
 const routes = [].concat(
   getStatus,
@@ -80,7 +82,9 @@ const routes = [].concat(
   retrieveAppointment,
   retrieveAdviceAndGuidanceOverviewPdf,
   searchServiceRequest,
-  requestUploadUri
+  requestUploadUri,
+  retrieveBinary,
+  retrieveBinaryHelper
 )
 
 module.exports = routes

sandbox/src/routes/r4/retrieveBinary.js

@@ -0,0 +1,34 @@
+const businessFunctionValidator = require('../../services/businessFunctionValidator')
+
+module.exports = [
+  /**
+   * Sandbox implementation for retrieveBinary A039 (R4) endpoint
+   */
+  {
+    method: 'GET',
+    path: '/FHIR/R4/Binary/{attachmentUuid}',
+    handler: (request, h) => {
+
+      const allowedBusinessFunctions = ["REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN", "SERVICE_PROVIDER_CLINICIAN", "SERVICE_PROVIDER_CLINICIAN_ADMIN"]
+
+      const validationResult = businessFunctionValidator.validateBusinessFunction(request, h, allowedBusinessFunctions)
+      if (validationResult) {
+        return validationResult
+      }
+
+      const uuid = request.params.attachmentUuid;
+      const url = request.url.href;
+      const objectStore = "/ObjectStore/RetrieveBinary/d497bbe3-f88b-45f1-b3d4-9c563e4c0f5f";
+      const location = url.split('/FHIR')[0] + objectStore;
+
+      if (uuid === '704c3791-0873-45e9-9a04-b51996f8d93f' && request.method === 'get') {
+        const response = h.response().code(307)
+        response.headers["Location"] = location;
+        return response
+      } else {
+        return h.file('SandboxErrorOutcome.json').code(422);
+      }
+
+    }
+  }
+]

sandbox/src/routes/r4/retrieveBinaryHelper.js

@@ -0,0 +1,25 @@
+module.exports = [
+  /**
+   * Sandbox implementation for retrieveBinary (R4) endpoint helper, 
+   * with an ObjectStore 'mock', allowing redirection and example file retrieval.
+   */
+  {
+    method: 'GET',
+    path: '/ObjectStore/RetrieveBinary/{fileDownloadUuid}',
+    handler: (request, h) => {
+
+      const uuid = request.params.fileDownloadUuid
+      const exampleResponsePath = 'retrieveAttachment/responses/example_attachment.pdf'
+      const filename = 'example_attachment.pdf'
+      const responseCode = 200
+
+      if (uuid === 'd497bbe3-f88b-45f1-b3d4-9c563e4c0f5f') {
+        return h.file(exampleResponsePath, {
+          mode: 'attachment',
+          filename: filename,
+          etagMethod: false
+        }).code(responseCode);
+      }
+    }
+  }
+]

scripts/populate_placeholders.py

@@ -46,6 +46,7 @@ def main():
         "[[HYPERLINK_A039]]": "[A039 - Request pre-signed URL to upload file to document store](#api-Default-a039-request-pre-signed-url-for-file-upload)",
         "[[HYPERLINK_A040]]": "[A040 - Retrieve e-RS-Specific Practitioner Information](#api-Default-a040-retrieve-practitioner-info)",
         "[[HYPERLINK_A041]]": "[A041 - Search service request](#api-Default-a041-search-service-request)",
+        "[[HYPERLINK_A042]]": "[A042 - Request pre-signed URL to download file from document store](#api-Default-a042-request-pre-signed-url-for-file-download)",
         "[[HYPERLINK_A043]]": "[A043 - Retrieve advice and guidance overview PDF](#api-Default-a043-retrieve-advice-and-guidance-overview-pdf)",
         "[[HYPERLINK_ONBOARDING]]": "[onboarding](#api-description__onboarding)",
         "[[HYPERLINK_STABLE]]": "[stable](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status)",

scripts/validate_oas_examples.py

@@ -33,7 +33,7 @@
 http_methods = ["post", "put", "patch", "get"]
 
 # List containing http success response codes
-http_success_codes = ["200", "201"]
+http_success_codes = ["200", "201", "307"]
 
 # Open OAS JSON file
 try:
@@ -141,6 +141,7 @@ def get_success_code(endpoint, http_method):
         oas_spec_from_yaml["paths"][endpoint][http_method]["responses"].keys()
     )
     filtered_code = filter(lambda x: x in http_success_codes, endpoint_return_codes)
+
     return list(filtered_code)[0]
 
 

specification/components/r4/schemas/path/AttachmentUuid.yaml

@@ -0,0 +1,8 @@
+in: path
+name: id
+description: | 
+  Reference for an attachment, as provided in the response from [[HYPERLINK_A039]].
+required: true
+schema:
+  type: string
+  example: '704c3791-0873-45e9-9a04-b51996f8d93f'

specification/components/r4/schemas/responses/retrieveBinary/307Response.yaml

@@ -0,0 +1,12 @@
+description: Response redirects user agent to the large file attachment URL in the Object Store via the Location header.
+headers:
+  x-correlation-id:
+    $ref: '../../headers/response/CorrelationID.yaml'
+  x-request-id:
+    $ref: '../../headers/response/RequestID.yaml'
+  Location:
+    description: The large file attachment location in the Object Store.
+    required: true
+    schema:
+      type: string
+      example: '<ObjectStoreURL>'

specification/components/r4/schemas/responses/retrieveBinary/400Response.yaml

@@ -0,0 +1,20 @@
+description: |
+  Where status code 400 (Bad Request) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below.
+  Check diagnostics property for specific information regarding the error.
+  
+  | issue.details.coding.code | issue.code   | Description                                           |
+  | ------------------------- | ------------ | ----------------------------------------------------- |
+  | REC_BAD_REQUEST           | required     | TODO:63315          |
+headers:
+  x-correlation-id:
+    $ref: '../../headers/response/CorrelationID.yaml'
+  x-request-id:
+    $ref: '../../headers/response/RequestID.yaml'
+  Content-Type:
+    $ref: '../../headers/response/ContentTypeFhirJson.yaml'
+content:
+  application/fhir+json:
+    schema:
+      $ref: '../../NHSDigital-OperationOutcome.yaml'
+    example:
+      $ref: '../../../examples/NHSDigital-OperationOutcome.json'

specification/e-referrals-service-api.yaml

@@ -3716,6 +3716,36 @@ paths:
           $ref: 'components/r4/schemas/responses/R4-TooManyRequests.yaml'
         '500':
           $ref: 'components/r4/schemas/responses/R4-InternalServerError.yaml'
+  /R4/Binary/{id}:
+    get:
+      security:
+        - bearerAuth: []
+      description: |
+        ### TODO Add later
+      summary: A042 - Request pre-signed URL to download file from document store
+      operationId: a042-request-pre-signed-url-for-file-download
+      parameters:
+        - $ref: 'components/r4/schemas/headers/request/BearerAuthorization.yaml'
+        - $ref: 'components/r4/schemas/headers/request/BusinessFunction.yaml'
+        - $ref: 'components/r4/schemas/headers/request/CorrelationID.yaml'
+        - $ref: 'components/r4/schemas/headers/request/OdsCode.yaml'
+        - $ref: 'components/r4/schemas/headers/request/OnBehalfOfUserID.yaml'
+        - $ref: 'components/r4/schemas/path/AttachmentUuid.yaml'
+      responses:
+        '307':
+          $ref: 'components/r4/schemas/responses/retrieveBinary/307Response.yaml'
+        '400':
+          $ref: 'components/r4/schemas/responses/retrieveBinary/400Response.yaml'
+        '401':
+          $ref: 'components/r4/schemas/responses/R4-Unauthorized.yaml'
+        '403':
+          $ref: 'components/r4/schemas/responses/R4-Forbidden.yaml'
+        '404':
+          $ref: 'components/r4/schemas/responses/R4-NotFound.yaml'
+        '429':
+          $ref: 'components/r4/schemas/responses/R4-TooManyRequests.yaml'
+        '500':
+          $ref: 'components/r4/schemas/responses/R4-InternalServerError.yaml'
 components:
   securitySchemes:
     bearerAuth: