# SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
#
# SPDX-License-Identifier: CC-BY-SA-4.0

openapi: 3.0.0
info:
  title: Hospital Source Data System API
  description: >-
    "APIs to fetch and receive basic patient information. These API facilitates various
    Opal functionality. At a minimum, the patient demographics lookup must be supported in order for Opal
    to successfully complete a patient registration."
  version: 1.1.0

tags:
  - name: demographics
    description: Endpoints for accessing patient demographic information
  - name: historical data
    description: Endpoints for providing historical patient data for newly registered Opal patients
  - name: update source
    description: Endpoints for updating the source data with information about the patient from Opal
  - name: wait room
    description: Endpoints for updating a hospital with waiting room management information about a patient

paths:
  /getPatientDemographicsByMRN:
    post:
      tags:
        - demographics
      summary: Retrieve patient demographic information by patient MRN
      description: "Fetch basic demographic details of a patient identified by MRN and site."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mrn:
                  description: "Patient's hospital card MRN"
                  type: string
                site:
                  description: "Patient's hospital card site identifier"
                  type: string
              required:
                - mrn
                - site
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/InvalidParameters'
        '404':
          $ref: '#/components/responses/PatientNotFound'

  /getPatientDemographicsByHIN:
    post:
      tags:
        - demographics
      summary: Retrieve patient demographic information by patient health insurance number
      description: "Fetch basic demographic details of a patient identified by the health insurance number."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                health_insurance_number:
                  description: "Patient's health insurance number"
                  type: string
              required:
                - health_insurance_number
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/InvalidParameters'
        '404':
          $ref: '#/components/responses/PatientNotFound'

  /updatePatientLocation:
    post:
      tags:
        - wait room
      summary: Update patient location in the hospital
      description: "Update the hospital with the patient's latest location within the waiting room."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                appointmentId:
                  description: "Unique identifier for the patient's appointment"
                  type: integer
                location:
                  description: "Current location of the patient within the hospital"
                  type: string
              required:
                - appointmentId
                - location
      responses:
        '200':
          description: Location updated successfully
        '400':
          description: Invalid Parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "400"
                  message:
                    type: string
                    example: "Invalid appointmentId or location provided."
        '404':
          description: The appointment could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "404"
                  message:
                    type: string
                    example: "The patient could not be found."

  /addPatientMeasurementDocument:
    post:
      tags:
        - update source
      summary: Add weight measurement document to patient chart
      description: "Add a PDF containing a patient's weight measurement information to the patient chart in the source system."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mrn:
                  type: string
                  example: "1111111"
                site:
                  type: string
                  example: "XXX"
                document:
                  type: string
                  example: "VERY_LONG_REPORT_PDF_BASE64_ENCODED_STRING"
                documentDatetime:
                  type: string
                  format: date-time
                  example: "2024-07-08T11:25:10Z"
      responses:
        '200':
          description: Document added successfully
        '400':
          description: Invalid JSON or Parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "400"
                  message:
                    type: string
                    example: "Invalid mrn or site provided."
        '404':
          description: The patient could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "404"
                  message:
                    type: string
                    example: "The patient could not be found."

  /addPatientQuestionnaireDocument:
    post:
      tags:
        - update source
      summary: Add questionnaire document to patient chart
      description: "Add a PDF containing a patient's questionnaire data to the patient chart in the source system."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mrn:
                  type: string
                  example: "1111111"
                site:
                  type: string
                  example: "XXX"
                document:
                  type: string
                  example: "VERY_LONG_REPORT_PDF_BASE64_ENCODED_STRING"
                documentDatetime:
                  type: string
                  format: date-time
                  example: "2024-07-08T11:25:10Z"
      responses:
        '200':
          description: Document added successfully
        '400':
          description: Invalid JSON or Parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "400"
                  message:
                    type: string
                    example: "Invalid mrn or site provided."
        '404':
          description: The patient could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "404"
                  message:
                    type: string
                    example: "The patient could not be found."

  /newOpalPatient:
    post:
      tags:
        - historical data
      summary: Notify institution of a new Opal patient and trigger historical data fetch
      description: "Notify the hospital that a new patient has registered with Opal, and trigger a sending of all available historical data to Opal via the existing source data endpoints"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mrn:
                  description: "Patient's hospital card MRN"
                  type: string
                site:
                  description: "Patient's hospital card site identifier"
                  type: string
              required:
                - mrn
                - site
      responses:
        '200':
          description: Notification received successfully
        '400':
          description: Invalid Parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "400"
                  message:
                    type: string
                    example: "Invalid mrn or site provided."
        '404':
          description: The patient could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "404"
                  message:
                    type: string
                    example: "The patient could not be found."

components:
  schemas:
    PatientData:
      type: object
      properties:
        first_name:
          type: string
          description: "Patient's first name"
        last_name:
          type: string
          description: "Patient's last name"
        alias:
          type: string
          description: "Patient alias"
        sex:
          type: string
          description: "Patient's gender"
        date_of_birth:
          type: string
          format: date
          description: "Patient's date of birth"
        deceased:
          type: string
          format: boolean
          description: "True if the patient is deceased, False otherwise"
        death_date_time:
          type: string
          format: datetime
          description: "Patient death date and time"
        health_insurance_number:
          type: string
          description: "Patient's health insurance number (if applicable)"
        mrns:
          type: array
          description: "List of MRN and site combinations associated with the patient"
          items:
            type: object
            properties:
              mrn:
                type: string
              site:
                type: string
      required:
        - first_name
        - last_name
        - sex
        - date_of_birth
        - health_insurance_number
        - mrns
        - deceased
        - death_date_time
  responses:
    SuccessResponse:
      description: Success
      content:
        application/json:
          schema:
              $ref: '#/components/schemas/PatientData'
    InvalidParameters:
      description: Invalid Parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: "400"
              message:
                type: string
                example: "Invalid parameter provided."
    PatientNotFound:
      description: The patient was not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: "404"
              message:
                type: string
                example: "The patient could not be found."