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

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

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

scripts/validate_oas_examples.py

@@ -36,7 +36,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:
@@ -149,6 +149,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.json'

specification/e-referrals-service-api.yaml

@@ -385,6 +385,9 @@ paths:
   /R4/ServiceRequest/{id}/$ers.generateUploadURI:
     post:
       $ref: 'components/r4/schemas/endpoints/a039-request-pre-signed-url-for-file-upload.yaml'
+  /R4/Binary/{id}:
+    get:
+      $ref: 'components/r4/schemas/endpoints/a042-request-pre-signed-url-for-file-download.yaml'
 components:
   securitySchemes:
     bearerAuth: