api.yaml

openapi: 3.0.3
info:
  title: Social Interaction Sensing API
  description: API for the Social Interaction Sensing project.
  version: 1.0.0
servers:
  - url: 'http://localhost:8080/v1/'
    description: Local Server
  - url: 'https://siapi.timweiss.dev/v1/'
    description: Tim's Test Server
paths:
  /study:
    get:
      description:
        Gets a list of all available studies in the system.
      tags:
        - study
      responses:
        '200':
          description: A list of all available studies.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Study'
    post:
      description:
        Creates a new study in the system.
      tags:
        - study
      security:
        - token: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Study'
      responses:
        '201':
          description: The study was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
  /study/{study_id}:
    get:
      description:
        Gets a specific study by ID.
      tags:
        - study
      parameters:
        - name: study_id
          in: path
          description: The ID of the study to get.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The study was found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '404':
          description: The study was not found.
  /study/{study_id}/questionnaire:
    get:
      description: Gets all available ESM questionnaires for this specific study.
      tags:
        - esm
      parameters:
        - name: study_id
          in: path
          description: The ID of the study to get questionnaires for.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A list of all available questionnaires for the study.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ESMQuestionnaire'
        '404':
          description: The study was not found.
    post:
      description: Creates a new ESM questionnaire for the study.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study to create the questionnaire for.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ESMQuestionnaire'
      responses:
        '201':
          description: The questionnaire was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESMQuestionnaire'
        '404':
          description: The study was not found.
  /study/{study_id}/questionnaire/{questionnaire_id}:
    get:
      description: Gets a specific ESM questionnaire by ID.
      tags:
        - esm
      parameters:
        - name: study_id
          in: path
          description: The ID of the study to get the questionnaire for.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire to get.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The questionnaire was found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESMFullQuestionnaire'
        '404':
          description: The questionnaire was not found.
    put:
      description: Updates an existing ESM questionnaire.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study that the questionnaire belongs to.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire to update.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ESMQuestionnaire'
      responses:
        '200':
          description: The questionnaire was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESMQuestionnaire'
        '404':
          description: The questionnaire was not found.
  /study/{study_id}/questionnaire/{questionnaire_id}/element:
    post:
      description: Adds a new element to an existing ESM questionnaire.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study that the questionnaire belongs to.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire to add the element to.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ESMElement'
      responses:
        '201':
          description: The element was added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESMElement'
        '404':
          description: The questionnaire was not found.
  /study/{study_id}/questionnaire/{questionnaire_id}/element/{element_id}:
    put:
      description: Updates an existing element in an ESM questionnaire.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study that the questionnaire belongs to.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire that the element belongs to.
          required: true
          schema:
            type: integer
        - name: element_id
          in: path
          description: The ID of the element to update.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ESMElement'
      responses:
        '200':
          description: The element was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESMElement'
        '404':
          description: The questionnaire was not found.
    delete:
      description: Deletes an existing element from an ESM questionnaire.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study that the questionnaire belongs to.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire that the element belongs to.
          required: true
          schema:
            type: integer
        - name: element_id
          in: path
          description: The ID of the element to delete.
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: The element was deleted successfully.
        '404':
          description: The questionnaire was not found.
  /study/{study_id}/questionnaire/{questionnaire_id}/trigger:
    post:
      description: Adds a new trigger to an existing ESM questionnaire.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study that the questionnaire belongs to.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire to add the trigger to.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ESMTrigger'
      responses:
        '201':
          description: The trigger was added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESMTrigger'
        '404':
          description: The questionnaire was not found.
  /study/{study_id}/questionnaire/{questionnaire_id}/trigger/{trigger_id}:
    put:
      description: Updates an existing trigger in an ESM questionnaire.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study that the questionnaire belongs to.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire that the trigger belongs to.
          required: true
          schema:
            type: integer
        - name: trigger_id
          in: path
          description: The ID of the trigger to update.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ESMTrigger'
      responses:
        '200':
          description: The trigger was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESMTrigger'
        '404':
          description: The questionnaire was not found.
    delete:
      description: Deletes an existing trigger from an ESM questionnaire.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study that the questionnaire belongs to.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire that the trigger belongs to.
          required: true
          schema:
            type: integer
        - name: trigger_id
          in: path
          description: The ID of the trigger to delete.
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: The trigger was deleted successfully.
        '404':
          description: The questionnaire was not found.
  /study/{study_id}/questionnaire/{questionnaire_id}/answer:
    post:
      description: Adds a new answer to an existing ESM questionnaire.
      tags:
        - esm
      security:
        - token: [ ]
      parameters:
        - name: study_id
          in: path
          description: The ID of the study that the questionnaire belongs to.
          required: true
          schema:
            type: integer
        - name: questionnaire_id
          in: path
          description: The ID of the questionnaire to add the answer to.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ESMAnswer'
      responses:
        '201':
          description: The answer was added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESMAnswer'
        '404':
          description: The questionnaire was not found.
  /enrolment:
    post:
      description:
        Enrols a participant in a study through the enrolment key.
      tags:
        - enrolment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - enrolment_key
              properties:
                enrolment_key:
                  type: string
                  description: The enrolment key for the study.
      responses:
        '201':
          description: The enrolment was created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  participantId:
                    type: string
                    description: The unique identifier for the participant.
                  token:
                    type: string
                    description: The authentication token for the participant.
                  studyId:
                    type: number
                    description: The database ID for the study.
        '400':
          description: The enrolment key was invalid (typo or study does not exist).
  /enrolment/{participant_id}:
    post:
      description:
        Re-enrols a participant through their participant ID.
      tags:
        - enrolment
      parameters:
        - name: participant_id
          in: path
          description: The ID of the participant to re-enrol.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Successfully re-enrolled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  participantId:
                    type: string
                    description: The unique identifier for the participant.
                  token:
                    type: string
                    description: The authentication token for the participant.
                  studyId:
                    type: number
                    description: The database ID for the study.
        '400':
          description: The participant ID was invalid (does not exist).
  /reading:
    post:
      description:
        Adds a new singular sensor reading to the system.
      tags:
        - reading
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SensorReading'
      security:
        - token: [ ]
      responses:
        '201':
          description: The sensor reading was added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SensorReading'
        '400':
          description: The sensor reading was invalid (missing data).
        '403':
          description: The sensor reading was not allowed (participant not enrolled).
        '401':
          description: The participant is not authenticated.
  /reading/batch:
    post:
      description:
        Adds a batch of sensor readings to the system.
      tags:
        - reading
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SensorReading'
      security:
        - token: [ ]
      responses:
        '201':
          description: The sensor readings were added successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SensorReading'
        '400':
          description: The sensor readings were invalid (missing data).
        '403':
          description: The sensor readings were not allowed (participant not enrolled).
        '401':
          description: The participant is not authenticated.
  /reading/{reading_id}/file:
    post:
      description:
        Adds a file to a specific reading.
      tags:
        - reading
      parameters:
        - name: reading_id
          in: path
          description: The ID of the reading to attach the file to.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/File'
      security:
        - token: [ ]
      responses:
        '201':
          description: The file was attached successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '400':
          description: The file was invalid (missing data).
        '403':
          description: The file was not allowed (participant not enrolled).
        '401':
          description: The participant is not authenticated.

components:
  securitySchemes:
    token:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    File:
      description: Attached file for a reading
      type: object
      required:
        - readingId
          - filename
      properties:
        id:
          type: integer
          description: The unique identifier for the file.
        readingId:
          type: integer
          description: The database ID for the reading.
        filename:
          type: string
          description: The name of the file.
        path:
          type: string
          description: The path to the file on the server.

    SensorReading:
      description: An atomic reading of a sensor. Tied to a specific participant and study.
      type: object
      required:
        - enrolmentId
        - sensorType
        - data
        - timestamp
      properties:
        id:
          type: integer
          description: The unique identifier for the sensor reading.
        enrolmentId:
          type: integer
          description: The database ID for the enrolment.
        sensorType:
          type: string
          description: The type of sensor that generated the reading.
        data:
          type: object
          description: The data from the sensor reading.
        timestamp:
          type: string
          description: The timestamp of the reading.

    Enrolment:
      type: object
      description: A single enrolment in a study.
      properties:
        id:
          type: integer
          description: The unique identifier for the enrolment.
        studyId:
          type: integer
          description: The database ID for the study.
        participantId:
          type: string
          description: The unique identifier for the participant. Can be used to re-identify the participant.

    Study:
      type: object
      description: A study in the system.
      required:
        - name
        - enrolmentKey
      properties:
        id:
          type: integer
          description: The unique identifier for the study.
        name:
          type: string
          description: The name of the study.
        enrolmentKey:
          type: string
          description: The enrolment key for the study. Needs to be unique across all studies.

    ESMQuestionnaire:
      description: Questionnaire that can be presented to the participant
      properties:
        id:
          type: integer
          description: The unique identifier for the questionnaire.
        studyId:
          type: integer
          description: The database ID for the study.
        name:
          type: string
          description: The name of the questionnaire.
        enabled:
          type: boolean
          description: Whether the questionnaire is enabled.
        version:
          type: number
          description: The version of the questionnaire.

    ESMElement:
      description: A visual or user entry element in a questionnaire
      properties:
        id:
          type: integer
          description: The unique identifier for the element.
        questionnaireId:
          type: integer
          description: The database ID for the questionnaire.
        type:
          type: string
          description: The type of element (e.g., text, radio, checkbox).
        step:
          type: number
          description: The step in the questionnaire.
        position:
          type: number
          description: The position of the element in the step.
        configuration:
          type: object
          description: The type-dependent configuration for the element.

    ESMTrigger:
      description: Conditional trigger for presenting an ESM questionnaire.
      properties:
        id:
          type: integer
          description: The unique identifier for the trigger.
        questionnaireId:
          type: integer
          description: The database ID for the questionnaire.
        type:
          type: string
          description: The type of trigger (e.g., time, after an event).
        configuration:
          type: object
          description: The type-dependent configuration for the trigger.

    ESMFullQuestionnaire:
      description: A full questionnaire with elements and triggers
      properties:
        questionnaire:
          $ref: '#/components/schemas/ESMQuestionnaire'
        elements:
          type: array
          items:
            $ref: '#/components/schemas/ESMElement'
        triggers:
          type: array
          items:
            $ref: '#/components/schemas/ESMTrigger'
    ESMAnswer:
      description: Instance of answered questionnaire
      properties:
        questionnaireId:
          type: integer
          description: The database ID for the questionnaire.
        enrolmentId:
          type: integer
          description: The unique identifier for the enrolment.
        answers:
          type: array
          description: The answers to the questionnaire.