ptm-api.yaml

# SPDX-FileCopyrightText: 2020, 2021, 2022 Lars Geyer-Blaumeiser <lars@lgblaumeiser.de>
# SPDX-License-Identifier: MIT
openapi: 3.0.0
info:
  title: Project Time Manager API
  description: Description of Project Time Manager API
  version: 2.0.0

servers:
  - url: http://localhost:8080
    description: Project time manager currently runs typically locally on the host machine

paths:

# Activity API

  /activities:
    get:
      summary: Return all activities of the user given by the authentication
      operationId: getActivities
      tags:
        - activities
      security:
        - BearerAuth: []
      parameters:
        - name: hidden
          description: A boolean indicating to show all activities including the hidden ones, defaults to false
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: List of all activities of the user 
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/Activities'
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      summary: Create a new activity for the user given by the authentication
      operationId: addActivity
      tags:
        - activities
      security:
        - BearerAuth: []
      requestBody:
        description: The data of the new activity. All elements of the data structure are mandatory
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewActivityData'
      responses:
        '201':
          description: Activity successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
          
  /activities/{activityId}:
    get:
      summary: Access an activity by id, if the resource belongs to user
      operationId: getActivity
      tags:
        - activities
      security:
        - BearerAuth: []
      parameters: 
        - name: activityId
          description: id of the requested activity
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: The requested activity 
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

    patch:
      summary: Change an existing activity, if the resource belongs to the user and the change is allowed
      operationId: changeActivity
      tags:
        - activities
      security:
        - BearerAuth: []
      parameters: 
        - name: activityId
          description: id of the requested activity
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The data for the change, all fields are optional, at least one must be changed
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeActivityData'
      responses:
        '200':
          description: Activity successfully changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      summary: Delete an activity, if the resource belongs to the user and the activity can be deleted
      operationId: deleteBooking
      tags:
        - activities
      security:
        - BearerAuth: []
      parameters:
        - name: activityId
          description: id of the activity to delete
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          $ref: '#/components/responses/SuccessfullyDeleted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

# Booking API

  /bookings:
    get:
      summary: Access bookings for the user of a day or a range of days
      operationId: getBookings
      tags:
        - bookings
      security:
        - BearerAuth: []
      parameters:
        - name: day
          description: A date string, return bookings from this day on including the day
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: until
          description: A date string, return bookings until this day excluding the day, not needed for single day requests
          in: query
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: List of all bookings of the user within the given time frame
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/Bookings'
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      summary: Create a new booking for the authenticated user
      operationId: addBooking
      tags:
        - bookings
      security:
        - BearerAuth: []
      requestBody:
        description: The data of the new booking, bookingday, starttime and activity are mandatory, endtime and comment are optional
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewBookingData'
      responses:
        '201':
          description: Booking successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /bookings/{bookingId}:
    get:
      summary: Access a booking, if the resource belongs to the user
      operationId: getBooking
      tags:
        - bookings
      security:
        - BearerAuth: []
      parameters:
        - name: bookingId
          description: id of the requested booking
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: The requested booking 
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

    patch:
      summary: Change an existing booking, if the resource belongs to the user
      operationId: changeBooking
      tags:
        - bookings
      security:
        - BearerAuth: []
      parameters: 
        - name: bookingId
          description: id of the booking to change
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The data to change in the booking, all fields are optional, at least one field must be changed
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangedBookingData'
      responses:
        '200':
          description: Booking successfully changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      summary: Add a break to the booking by splitting it, i.e., shorten the booking and create a second booking after the break, returns the uri of the created booking
      operationId: addBreak
      tags:
        - bookings
      security:
        - BearerAuth: []
      parameters:
        - name: bookingId
          description: id of the requested booking
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: The break data to be used in the split, breakstart is mandatory, breaklength is the length in minutes, it defaults to 30 minutes and is optional
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddBreak'
      responses:
        '201':
          description: Break created successfully, returned is the new booking after the break
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bookings'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

    delete:
      summary: Delete a booking, if the resource belongs to the user
      operationId: deleteBooking
      tags:
        - bookings
      security:
        - BearerAuth: []
      parameters:
        - name: bookingId
          description: id of the booking to delete
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          $ref: '#/components/responses/SuccessfullyDeleted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

# Analysis API

  /analysis/{analyzer}:
    get:
      summary: Get an analysis on the bookings in the given timeframe
      operationId: runAnalysis
      tags:
        - analysis
      security:
        - BearerAuth: []
      parameters: 
        - name: analyzer
          description: Name of the requested analyzer
          in: path
          required: true
          schema:
            type: string
            format: enum
        - name: startdate
          description: Start day for the analysis, including the given day
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: enddate
          description: End day for the analysis, excluding the given day
          in: query
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: The requested analysis result as a string table 
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/Analysis'
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

# Infrastructure API

  /backup:
    get:
      summary: Create a backup of the bookings of the user
      operationId: backup
      tags:
        - backup
      security:
        - BearerAuth: [ ]
      responses:
        '200':
          description: A backup of the database data as a zipped array of Booking objects
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

    put:
      summary: Restore a backup and replace existing bookings for the user
      operationId: restore
      tags:
        - backup
      security:
        - BearerAuth: [ ]
      requestBody:
        description: The data to restore in the database
        required: true
        content:
          application/zip:
            schema:
              type: string
              format: binary
      responses:
        '204':
          description: Database restored successfully, old data deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  
  /licenses:
    get:
      summary: Returns the attribution information on the used Open Source Software
      operationId: license
      tags:
        - legal
      responses:
        '200':
          description: The attribution information as text
          content:
            text/plain; charset=utf-8:
              schema:
                type: string
        '500':
          $ref: '#/components/responses/InternalError'

components:
  responses:
    SuccessfullyDeleted:
      description: Resource deleted successfully
    NoContent:
      description: The requested collection is empty
    Unauthorized:
      description: User not authorized
    BadRequest:
      description: Bad data given to the request, returns the error message of the server
      content:
        text/plain; charset=utf-8:
          schema:
            type: string
    Forbidden:
      description: The requested resource does not belong to the authenticated user
    InternalError:
      description: The request resulted in an unexpected error
      
  schemas:
    Activity:
      type: object
      properties:
        id:
          type: integer
          format: int64
        projectName:
          type: string
        activityName:
          type: string
        projectId:
          type: string
        activityId:
          type: string
        hidden:
          type: boolean
    
    NewActivityData:
      type: object
      required: [ projectName, projectId, activityName, activityId ]
      properties:
        projectName:
          type: string
        activityName:
          type: string
        projectId:
          type: string
        activityId:
          type: string
    
    ChangeActivityData:
      type: object
      properties:
        projectName:
          type: string
        activityName:
          type: string
        projectId:
          type: string
        activityId:
          type: string
        hidden:
          type: boolean
    
    Activities:
      type: array
      items:
        $ref: "#/components/schemas/Activity"

    Booking:
      type: object
      properties:
        id:
          type: integer
          format: int64
        bookingday:
          type: string
          format: date
        starttime:
          type: string
          format: time
        endtime:
          type: string
          format: time
        activity:
          type: string
        comment:
          type: string

    NewBookingData:
      type: object
      required: [ bookingday, starttime, activity ]
      properties:
        bookingday:
          type: string
          format: date
        starttime:
          type: string
          format: time
        endtime:
          type: string
          format: time
        activity:
          type: integer
          format: int64
        comment:
          type: string

    ChangedBookingData:
      type: object
      properties:
        bookingday:
          type: string
          format: date
        starttime:
          type: string
          format: time
        endtime:
          type: string
          format: time
        activity:
          type: integer
          format: int64
        comment:
          type: string

    Bookings:
      type: array
      items:
        $ref: "#/components/schemas/Booking"

    AddBreak:
      type: object
      required: [ breakstart ]
      properties:
        breakstart:
          type: string
          format: time
        breaklength:
          type: integer
          format: int32
      
    Analysis:
      type: array
      items:
        type: array
        items:
          type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT