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

Author: francisco-videira-nhs

sandbox/src/routes/index.js

@@ -42,6 +42,8 @@ const retrieveOboUsers = require('./r4/retrieveOboUsers')
 const retrieveHealthcareService = require('./r4/retrieveHealthcareService')
 const searchForHealthcareServices = require('./r4/searchForHealthcareServices')
 const searchServiceRequest = require('./r4/searchServiceRequest')
+const retrieveBinary = require('./r4/retrieveBinary')
+const retrieveBinaryHelper = require('./r4/retrieveBinaryHelper')
 
 const routes = [].concat(
   getStatus,
@@ -80,7 +82,9 @@ const routes = [].concat(
   retrieveAppointment,
   retrieveAdviceAndGuidanceOverviewPdf,
   searchServiceRequest,
-  createAdviceAndGuidance
+  createAdviceAndGuidance,
+  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

@@ -43,6 +43,7 @@ def main():
         "[[HYPERLINK_A038]]": "[Retrieve appointment (A038)](#get-/STU3/Appointment/-id-)",
         "[[HYPERLINK_A040]]": "[Retrieve “on-behalf-of” practitioner user information (A040)](#get-/R4/Practitioner)",
         "[[HYPERLINK_A041]]": "[Search for service requests (A041)](#get-/R4/ServiceRequest)",
+        "[[HYPERLINK_A042]]": "[Request pre-signed URL to download file from document store (A042)](#get-/R4/Binary/-id-)",
         "[[HYPERLINK_A043]]": "[Retrieve advice and guidance overview PDF (A043)](#post-/STU3/CommunicationRequest/-ubrn-/$ers.generateCRI)",
         "[[HYPERLINK_A044]]": "[Create advice and guidance request (A044)](#post-/STU3/CommunicationRequest/$ers.createAdviceAndGuidance)",
         "[[HYPERLINK_ONBOARDING]]": "[onboarding](#overview--onboarding)",

scripts/validate_oas_examples.py

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

specification/components/r4/schemas/endpoints/a042-request-pre-signed-url-for-file-download.yaml

@@ -0,0 +1,28 @@
+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: '../headers/request/BearerAuthorization.yaml'
+  - $ref: '../headers/request/BusinessFunction.yaml'
+  - $ref: '../headers/request/CorrelationID.yaml'
+  - $ref: '../headers/request/OdsCode.yaml'
+  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
+  - $ref: '../pathParameters/AttachmentUuid.yaml'
+responses:
+  '307':
+    $ref: '../responses/retrieveBinary/307Response.yaml'
+  '400':
+    $ref: '../responses/retrieveBinary/400Response.yaml'
+  '401':
+    $ref: '../responses/Unauthorized.yaml'
+  '403':
+    $ref: '../responses/Forbidden.yaml'
+  '404':
+    $ref: '../responses/NotFound.yaml'
+  '429':
+    $ref: '../responses/TooManyRequests.yaml'
+  '500':
+    $ref: '../responses/InternalServerError.yaml'

specification/components/r4/schemas/pathParameters/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-400.json'

specification/e-referrals-service-api.yaml

@@ -426,7 +426,9 @@ paths:
   /R4/ServiceRequest:
     get:
       $ref: 'components/r4/schemas/endpoints/a041-search-service-request.yaml'
-
+  /R4/Binary/{id}:
+    get:
+      $ref: 'components/r4/schemas/endpoints/a042-request-pre-signed-url-for-file-download.yaml'
 components:
   securitySchemes:
     bearerAuth: