openapi.yaml

openapi: 3.0.1
info:
  title: Scenario 1 API
  description: This is the API to the FSI Autism Hackathon Scenario 1, IoT.
  version: 1.0.0
tags:
  - name: Patients
    description: Information regarding patients
  - name: Users
    description: Information about the therapists, parents, teachers, and other guardians who may be responsible for a patient.

components:
  schemas:
    Metric:
      properties:
        id:
          type: string
          format: uuid
        objectiveId:
          $ref: "#/components/schemas/ObjectiveId"
        startTime:
          type: string
          format: date-time
          example: "2017-07-21T17:32:28Z"
        endTime:
          type: string
          format: date-time
          nullable: true
          example: "2017-07-21T17:32:28Z"
    Objective:
      properties:
        id:
          $ref: "#/components/schemas/ObjectiveId"
        patientId:
          $ref: "#/components/schemas/PatientId"
        description:
          type: string
          example: Tantrum Duration
        type:
          type: string
          enum:
            - Counter
            - Duration
            - Latency
      required:
        - id
        - patientId
        - description
        - type
    ObjectiveId:
      type: string
      format: uuid
    Patient:
      properties:
        id:
          $ref: "#/components/schemas/PatientId"
        firstName:
          type: string
          example: Jane
        surname:
          type: string
          example: Doe
      required:
        - id
        - surname
    PatientId:
      type: string
      format: uuid
    User:
      properties:
        id:
          $ref: "#/components/schemas/UserId"
        username:
          type: string
          example: jdoe
        firstName:
          type: string
          example: Jane
        surname:
          type: string
          example: Doe
      required:
        - id
        - username
    UserId:
      type: string
      format: uuid

paths:
  /patients:
    get:
      tags: [ Patients ]
      summary: Returns a list of patients, ordered by surname, then first name
      operationId: getPatients
      responses:
        "200":
          description: List successfully retrieved
          content:
            application/json:
              schema:
                properties:
                  patients:
                    type: array
                    items:
                      $ref: "#/components/schemas/Patient"
        "403":
          description: Access denied
    post:
      summary: Creates a new patient
      operationId: addPatient
      tags: [ Patients ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  minLength: 1
                surname:
                  type: string
                  minLength: 1
              required:
                - firstName
                - surname
      responses:
        "201":
          description: The patient was created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Patient"
        "403":
          description: Access denied
        "405":
          description: The patient information was formatted incorrectly.

  /patients/{patientId}:
    get:
      operationId: getPatient
      tags: [ Patients ]
      summary: Retrieves a patient's details
      parameters:
        - in: path
          name: patientId
          required: true
          schema:
            $ref: "#/components/schemas/PatientId"
      responses:
        "200":
          description: Patient successfully retrieved
          content:
            application/json:
              schema:
                properties:
                  patient:
                    $ref: "#/components/schemas/Patient"
        "403":
          description: Access denied
        "404":
          description: Patient not found

  /patients/{patientId}/objectives:
    get:
      operationId: getObjectives
      tags: [ Patients ]
      summary: Retrieves a list of all the patient's current objectives
      parameters:
        - in: path
          name: patientId
          required: true
          schema:
            $ref: "#/components/schemas/PatientId"
      responses:
        "200":
          description: Patient successfully retrieved
          content:
            application/json:
              schema:
                properties:
                  objectives:
                    type: array
                    items:
                      $ref: "#/components/schemas/Objective"
        "403":
          description: Access denied
        "404":
          description: Patient not found
    post:
      operationId: createObjective
      tags: [ Patients ]
      summary: Creates a new objective for the patient
      parameters:
        - in: path
          name: patientId
          required: true
          schema:
            $ref: "#/components/schemas/PatientId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  description: The description of the objective
                  type: string
                type:
                  type: string
                  enum:
                    - Counter
                    - Duration
                    - Latency
              required:
                - description
                - type
      responses:
        "200":
          description: Objective successfully created
          content:
            application/json:
              schema:
                properties:
                  objective:
                    $ref: "#/components/schemas/Objective"
        "403":
          description: Access denied
        "404":
          description: Patient not found

  /patients/{patientId}/objectives/{objectiveId}:
    get:
      operationId: getObjective
      tags: [ Patients ]
      summary: Retrieves a patient's particular objective
      parameters:
        - in: path
          name: patientId
          required: true
          schema:
            $ref: "#/components/schemas/PatientId"
        - in: path
          name: objectiveId
          required: true
          schema:
            $ref: "#/components/schemas/ObjectiveId"
        - in: query
          name: include-data
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Objective successfully retrieved.
          content:
            application/json:
              schema:
                properties:
                  objective:
                    $ref: "#/components/schemas/Objective"
                  data:
                    description: If 'include-data' has been set to 'true', will be included
                    nullable: true
                    type: array
                    items:
                      $ref: "#/components/schemas/Metric"

        "403":
          description: Access denied
        "404":
          description: Patient or objective not found

  /patients/{patientId}/objectives/{objectiveId}/record:
    post:
      operationId: recordObjectiveMetric
      tags: [ Patients ]
      summary: Records a new count for the patient's objective
      parameters:
        - in: path
          name: patientId
          required: true
          schema:
            $ref: "#/components/schemas/PatientId"
        - in: path
          name: objectiveId
          required: true
          schema:
            $ref: "#/components/schemas/ObjectiveId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                startTime:
                  type: string
                  format: date-time
                  example: "2017-07-21T17:32:28Z"
                endTime:
                  type: string
                  format: date-time
                  example: "2017-07-21T17:32:28Z"
              required:
                - startTime                  
      responses:
        "204":
          description: Recorded Successfully
        "403":
          description: Access denied
        "404":
          description: Patient or objective not found