api.raml

#%RAML 1.0
title: BRN API
version: v1
baseUri: http://localhost:8081/api
mediaType:
  - application/json
types:
  pageable: !include datatypes/pageable.raml
annotationTypes:
  deprecated:
    properties:
      replaceWith:
        type: string
        description: |
          Describe the alternative resource/method that can be used as a substitute.
        required: true
      since:
        type: string
        pattern: (0[1-9]|10|11|12)/20[0-9]{2}
        required: false
        description: Describe when the resource/method became deprecated in the format (mm/YYYY)
    allowedTargets: [Resource, Method]
    displayName: Deprecated
    description: |
      A deprecated resource or method is *not* recommended for new work.
      The resource or method will be removed in a future version of the API.
      Deprecation does NOT mean it is not supported anymore in the current version.

# STATISTICS ----------------------------------
/statistics:
  /subgroups:
    get:
      description: Get user's subgroup statistics
      queryParameters:
        ids:
          required: true
          type: array
          items:
            type: integer
            format: int64
          example: [1,2]
      responses:
        200:
          body:
            example: {
              data: [
                {
                  subGroupId: 1,
                  completedExercises: 0,
                  totalExercises: 28
                },
                {
                  subGroupId: 2,
                  completedExercises: 0,
                  totalExercises: 56
                }
              ],
              errors: [],
              meta: []
            }

# AUDIOMETRY-----------------------------------
/audiometrics:
  description: Contains actions for audiometry
  get:
    description: Get audiometrics without tasks
    queryParameters:
      locale:
        required: false
        type: string
        example: "en-us"
        default: "ru-ru"
    responses:
      200:
        body:
          example: !include samples/audiometrics.json
  /{audiometryId}:
    get:
      description: Get audiometry for id with tasks
      responses:
        200:
          body:
            examples:
              example1: !include samples/audiometry_1_signals.json
              example2: !include samples/audiometry_2_speech.json
/audiometry-history:
  description: Contains actions for audiometry history
  post:
    description: Save speech audiometry history
    body:
      examples:
        example1: !include samples/audiometryHistoryRequest.json
        example2: !include samples/audiometryHistoryRequestSignal.json
    responses:
      200:
        body:
          example: 25

# AUDIO GENERATION ----------------------------
/audio:
  description: Contains actions for getting audio file for words
  get:
    description: Get audio resource for string
    queryParameters:
      text:
        required: true
        type: string
        example: "London is the capital"
      exerciseId:
        required: true
        type: integer
        example: 1
      locale:
        required: false
        type: string
        example: "en-us"
        default: "ru-ru"
    responses:
      200:
        body:
          example: !include samples/audio.ogg

# CONTRIBUTORS ----
/contributors
  get:
    queryParameters:
      locale:
        required: false
        type: string
        example: "ru-ru"
      type:
        required: false
        type: string
        example: "DEVELOPER"
    responses:
      200:
        body:
          example: !include samples/contributors.json

# GROUP ----------------------------
/groups:
  description: Contains actions over groups
  get:
    description: Get all groups by locale if it was set
    queryParameters:
      locale:
       required: false
       type: string
       example: "ru-ru"
    responses:
      200:
        body:
          example: !include samples/groups.json
  /{groupId}:
    get:
      description: Get group by id
      responses:
        200:
          body:
            example: !include samples/group.json

# SERIES ----------------------------
/series:
  description: Contains actions over series
  get:
    description: Get all series for group
    queryParameters:
      groupId:
        description: "ID of the group series belongs to"
        required: true
        type: string
        example: "42"
    responses:
      200:
        body:
          example: !include samples/series_by_group.json
  /{seriesId}:
    get:
      description: Get serie for id
      responses:
        200:
          body:
            example: !include samples/series.json
  /fileFormat/{seriesId}:
    get:
      description: Get series file format by series id
      responses:
        200:
          body:
            example: !include samples/file_format.json

# SUBGROUP ----------------------------
/subgroups:
  description: Contains actions over subgroup
  get:
    description: Get subgroups for series
    queryParameters:
      seriesId:
        description: "ID of the series belongs to"
        required: true
        type: string
        example: "42"
    responses:
      200:
        body:
          example: !include samples/subgroup_by_series.json
  post:
     description: Add new subgroup for existing series
     queryParameters:
       seriesId:
         description: "ID of the series"
         type: integer
         format: int64
         example: 1
     body:
       example: !include samples/add_subgroup_to_series.json
     responses:
       201:
         body:
           example: !include samples/add_subgroup_to_series_response.json
  /{subGroupId}:
    get:
      description: Get subgroup for id
      responses:
        200:
          body:
            example: !include samples/subgroup_by_id.json
    patch:
      description: Update subgroup by id
      body:
        example: !include samples/subgroup_patch_body.json
      responses:
        200:
          body:
            example: !include samples/subgroup_by_id.json
    delete:
      description: Delete subgroup by id without exercises
      queryParameters:
        subGroupId:
          description: "ID of the subGroup tasks belongs to"
          required: true
          type: string
          example: "3"
      responses:
        204:
        400:
          description: |
             Bad or not empty subGroup. This can happen if the user inserts
             incorrect number of subGroup or subGroup has exercises.
          body:
            example: {
              data: [],
              errors: ["Can not delete subGroup because subGroup is not found by this id."],
              meta: []
            }

# EXERCISE ----------------------------
/exercises:
  description: Contains actions over exercises
  get:
    description: Get exercises for subgroup with tasks. If called by current user, availability calculation is included
    queryParameters:
      subGroupId:
        description: "ID of the subgroup exercises belongs to"
        required: true
        type: string
        example: "42"
    responses:
      200:
        body:
          examples:
            example1: !include samples/exercises_for_1_series_subgroup.json
            example2: !include samples/exercises_for_2_series_subgroup.json
            example3: !include samples/exercises_for_3_series_subgroup.json
            example4: !include samples/exercises_for_4_series_subgroup.json
  post:
    description: Create new exercise for exist subgroup
    body:
      examples:
        example_words: !include samples/exerciseWordsCreateRequest.json
        example_phrases: !include samples/exercisePhrasesCreateRequest.json
        example_sentences: !include samples/exerciseSentencesCreateRequest.json
    responses:
      201:
        body:
          examples:
            example_words: !include samples/exerciseWordsResponse.json
            example_phrases: !include samples/exercisePhrasesResponse.json
            example_sentences: !include samples/exerciseSentencesResponse.json
  /{exerciseId}:
    get:
      descritpion: Get exercise by id
      responses:
        200:
          body:
            examples:
              example1: !include samples/exercise_for_id_1.json
              example2: !include samples/exercise_for_frequency_words_series.json
  /byWord
    get:
      description: Get exercises by word
      queryParameters:
        word:
          description: "Word which should be contained by exercise answers"
          required: true
          type: string
          example: "table"
      responses:
        200:
          body:
            examples: !include samples/exercises_with_words.json

  /byIds:
    post:
        description: Get available exercise ids for current user by input ids which have same subgroup
        body:
          example: !include samples/exercise_request.json
        responses:
          200:
            body:
              example: !include samples/avaliable_exercise_ids_by_input_ids.json
  /{exerciseId}/active/{active}:
    put:
      description: Update active status of the exercise
  /loadTasksFile:
    post:
      description: Load task file to series
      body:
        multipart/form-data:
          properties:
            seriesId:
              description: "ID of the series created exercises belongs to"
              required: true
              type: string
              example: "42"
            taskFile:
              description: |
                File with tasks to be uploaded
                - format for series 1:
                  orderNumber word audioFileName pictureFileName words wordType
                  1 бал no_noise/бал.mp3 pictures/бал.jpg (бам,сам,дам,зал,бак) OBJECT
                - format for series 2
                  orderNumber words
                  1 [(),(),(мальчик, девочка), (сидит, слушает),(),()]
              required: true
              type: file
        responses:
          201:

# TASK ----------------------------
/tasks:
  description: Contains actions over tasks
  get:
    description: Get all tasks by exercise id
    queryParameters:
      exerciseId:
        description: "ID of the exercise tasks belongs to"
        required: true
        type: string
        example: "3"
    responses:
      200:
        body:
          examples:
            example_for_1_series: !include samples/tasks_by_exercise_for_1_series.json
            example_for_2_series: !include samples/tasks_by_exercise_for_2_series.json
  /{taskId}:
    get:
      description: Get a task by id
      responses:
        200:
          body:
            examples:
              example_for_1_series: !include samples/task_by_id_for_1_series.json
              example_for_2_series: !include samples/task_by_id_for_2_series.json
              example_for_3_series: !include samples/task_by_id_for_3_series.json
              example_for_4_series: !include samples/task_by_id_for_4_series.json
              example_for_frequency_words_series: !include samples/task_by_id_for_frequency_words_series.json

# STUDY_HISTORY ----------------------
/study-history:
  description: Contains actions over the results of finished exercise
  post:
    description: Save current user's study history
    body:
      example: !include samples/study_history.json
    responses:
      201:
        body:
          example: !include samples/study_history_response.json
  /todayTimer:
    get:
      description: Get current user's today work time execution seconds
      responses:
        200:
          body:
            example: {
              data: 60,
              errors: [],
              meta: []
            }
  /monthHistories:
    get:
      description: Get current user's month study histories by month and year
      queryParameters:
        month:
          required: true
          type: integer
          example: 11
        year:
          required: true
          type: integer
          example: 2020
        userId:
          type: integer
          format: int64
          example: 1
      responses:
        200:
          body:
            example: !include samples/study_histories_dto_response.json
   /user/{userId}/has/statistics
      get:
       description: Check if user has statistics
        responses:
          200:
            body:
              example: true


# USERS ----------------------
/users:
  description: Contains actions over user details and accounts
  get:
    description: Get all users
    queryParameters:
      withAnalytics:
        required: false
        default: false
        type: boolean
        example: true
      role:
        required: false
        default: "ROLE_USER"
        type: string
      pageable:
        required: false
        type: pageable
    responses:
      200:
        body:
          examples:
            example1: !include samples/users_get_response.json
            example2: !include samples/users_with_analytics_get_response.json
  /{userId}:
    get:
      description: Get user by id
      responses:
        200:
          body:
            example: !include samples/user_get_response.json
    /headphones:
      post:
        description: Add headphones to the user
        body:
          example: !include samples/add_headphones.json
        responses:
          201:
            body:
              example: !include samples/add_headphones_response.json
      get:
        description: Get all headphones for user
        responses:
          200:
            body:
              example: !include samples/get_headphones_response.json
  /current:
    get:
      description: Get current logged in user
      responses:
        200:
          body:
            example: !include samples/user_get_response.json
    patch:
      description: Update current logged in user
      body:
        example: !include samples/user_patch_body.json
      responses:
        200:
          body:
            example: !include samples/user_get_response.json
    /avatar:
      put:
        description: Update avatar current user
        queryParameters:
          avatar:
            description: "Path to avatar"
            required: true
            type: string
            example: "/pictures/avatar/girl.svg"
        responses:
          200:
            body:
              example: !include samples/user_get_response.json
    /headphones:
      post:
        description: Add headphones to current user
        body:
          example: !include samples/add_headphones.json
        responses:
          201:
            body:
              example: !include samples/add_headphones_response.json
      get:
        description: Get all headphones for current user
        responses:
          200:
            body:
              example: !include samples/get_headphones_response.json

      /{headphonesId}:
        description: Delete headphone by id
        responses:
          200
    /{patientId}/doctor:
      get:
        description: Get patient's doctor
        responses:
          200:
            body:
              application/json:
                example: !include samples/get_doctor_assigned_to_patient_response.json
      delete:
        description: Delete doctor from patient
        responses:
          200
    /autotest/del
     delete:
       description: Delete autotest users by given prefix
       responses:
         200:
           body:
             application/json:
               example: !include samples/user_deletion_result.json
    /autotest/del/{email}
         delete:
           description: Delete autotest user by email
           responses:
             200:
               body:
                 application/json:
                   example: !include samples/user_deletion_result.json

# CLOUD  ----------------------
/cloud:
  description: Contains actions for cloud upload and bucket listing
  /folders:
    get:
      description: Get cloud folder structure
      responses:
        200:
          body:
            example: !include samples/cloud_folders.json
  /upload:
    get:
      description: Get cloud upload form
      queryParameters:
        filename:
          description: "File name to be used for uploading"
          required: true
          type: string
          example: "file1.jpg"
      responses:
        200:
          body:
            examples:
              example_for_aws_upload_form: !include samples/example_for_aws_upload_form.json
              example_for_google_upload_form: !include samples/example_for_google_upload_form.json
    /picture:
      post:
        description: Load unverified files to cloud storage
        body:
          multipart/form-data:
            properties:
              file:
                description: "File content"
                required: true
                type: file
        responses:
          200:
    /upload/contributor/picture:
      post:
        description: Upload unverified files for contributor pictures
        body:
          multipart/form-data:
            properties:
              file:
                description: "File content"
                required: true
                type: file
        responses:
          201:
            body:
              example: ""
  /url:
    get:
      description: Get cloud bucket url
      responses:
        200:
          body:
            example: "https://cloudprovider.bucket.com"
  /baseFileUrl:
    get:
      description: Get cloud base file url
      responses:
        200:
          body:
            example: "https://cloudprovider.bucket.com"

# DOCTOR  ----------------------
/doctors:
  description: Contains actions for doctor
  /{doctorId}/patients:
    post:
      description: Add patient to doctor
      body:
        application/json:
          example: !include samples/add_patient_to_doctor_request.json
      responses:
        200:
    get:
      description: Get all patients for doctor
      responses:
        200:
          body:
            application/json:
              example: !include samples/get_all_patient_for_doctor_response.json
    /{patientId}:
      delete:
        description: Delete patient from doctor
        responses:
          200:

# ROLES  ----------------------
/roles:
  description: Contains actions over roles
  get:
    description: Get all roles
    responses:
      200:
        body:
          example: !include samples/roles_get_response.json

# RESOURCES  ----------------------
/resources:
  /{id}:
    patch:
      description: Update resource description by resource id
      body:
        example: !include samples/update_resource_description_request.json
      responses:
        200:
          body:
            example: !include samples/resource_dto_response.json

################################
# V2 API ----------------------#
################################
/v2:
  description: Second version of API
  # STATISTICS ----------------------------------
  /statistics:
    description: Contains actions over user statistic details
    /study/day:
      get:
        description: Get user's details daily statistic for the day. Where day is a date in the ISO date time format
        queryParameters:
          userId:
            type: integer
            format: int64
            example: 1
          day:
            required: true
            type: datetime-only
            example: 2000-10-21T15:00:00
        responses:
          200:
            body:
              example: {
                data: [
                  {
                    seriesName: "Seria 1",
                    doneExercises: 10,
                    attempts: 1,
                    doneExercisesSuccessfullyFromFirstTime: 5,
                    listenWordsCount: 50
                  }, {
                    seriesName: "Seria 2",
                    doneExercises: 5,
                    attempts: 0,
                    doneExercisesSuccessfullyFromFirstTime: 5,
                    listenWordsCount: 25
                  }
                ],
                errors: [ ],
                meta: [ ]
              }
    /study/week:
      get:
        description: Get user's weekly statistic for period. Where period is a two dates in the ISO date time format
        queryParameters:
          from:
            required: true
            type: datetime-only
            example: 2000-11-23T15:00:00
          to:
            required: true
            type: datetime-only
            example: 2000-11-23T15:00:00
          userId:
            type: integer
            format: int64
            example: 1
        responses:
          200:
            body:
              example: {
                data: [
                  {
                    date: 2000-11-23T15:00:00,
                    exercisingTimeSeconds: 3000,
                    progress: GREAT
                  }
                ],
                errors: [],
                meta: []
              }
    /study/year:
      get:
        description: Get user's yearly statistic for period. Where period is a two dates in the ISO date time format
        queryParameters:
          from:
            required: true
            type: datetime-only
            example: 2000-11-23T15:00:00
          to:
            required: true
            type: datetime-only
            example: 2000-11-23T15:00:00
          userId:
            type: integer
            format: int64
            example: 1
        responses:
          200:
            body:
              example: {
                data: [
                  {
                    date: 2000-11-23T15:00:00,
                    exercisingDays: 15,
                    exercisingTimeSeconds: 3000,
                    progress: GREAT
                  }
                ],
                errors: [],
                meta: []
              }

  # STUDY_HISTORY ----------------------
  /study-history:
    description: Contains actions over the results of finished exercise
    /histories:
      get:
        description: |
          Get user's study histories for period from <= startTime <= to where startTime is a date in ISO date time format
        queryParameters:
          userId:
            type: integer
            example: 1
          from:
            required: true
            type: datetime-only
            example: 2000-10-21T15:00:00
          to:
            required: true
            type: datetime-only
            example: 2000-10-21T15:00:00
        responses:
          200:
            body:
              example: !include samples/study_histories_dto_response.json