SplittyAPI.yaml

openapi: '3.0.2'
info:
  title: Splitty API
  description: |
    This file maps out the endpoints for the OOP project, also known as Splitty.
  version: "1.1"

servers:
  - url: http://localhost:8080

tags:
  - name: Event
    description: Endpoints related to modify data connected to Events
  - name: Participant
    description: Endpoints related to modify data connected to Participants
  - name: Expense
    description: Endpoints related to modify data connected to Expenses
  - name: Admin
    description: Endpoints to obtain admin privileges

paths:
  /api/events:
    get:
      tags:
        - Event
      summary: Get events
      description: Gets all events currently stored in the Splitty application
      operationId: getAllEvents

      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'

    post:
      tags:
        - Event
      summary: Create event
      description: Create a new Event in the Splitty application
      operationId: createEvent

      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: TestName
                
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'

    delete:
      tags:
        - Event
      summary: Delete all events
      description: Deletes all the events from the database
      operationId: deleteEvents

      parameters:
        - name: password
          in: query
          description: The admin password
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Deleted
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        "401":
          description: Unauthorized. The password is incorrect


  /api/events/{eventId}:
    get:
      tags:
        - Event
      summary: Get event
      description: Gets a specific event stored in the Splitty application based on its id
      operationId: getEvent

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long

      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        "404":
          description: The event does not exist

    put:
      tags:
        - Event
      summary: Update event
      description: Updates the event information based on the Event object passed to it via the request body
      operationId: updateEvent

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long

      requestBody: 
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"

      responses:
        "201":
          description: Event updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Event"
        "404":
          description: The event does not exist

    delete:
      tags:
        - Event
      summary: Delete event
      description: Deletes an events from the database
      operationId: deleteEvent

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long
        - name: password
          in: query
          description: The admin password
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        "401":
          description: Unauthorized. The password is incorrect
        "404":
          description: The event does not exist


  /api/events/{eventId}/participants:
    get:
      tags:
        - Participant
      summary: Get all participants
      description: Gets all the participants of an event identified by its id
      operationId: getAllParticipants

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long

      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Participant'
        "404":
          description: The event does not exist
    
    post:
      tags:
        - Participant
      summary: Create participant
      description: Updates the participant information of an event based on the object passed to it via the request body
      operationId: createParticipant

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long

      requestBody: 
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'

      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Event"
        "404":
          description: The event does not exist


  /api/events/{eventId}/participants/{partId}:
    get:
      tags:
        - Participant
      summary: Get participant
      description: Gets a participants of an event identified by its id
      operationId: getParticipant

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long
        - name: partId
          in: path
          description: The id of the participant
          required: true
          schema:
            type: number
            format: long

      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        "400":
          description: The participant does not belong to the event
        "404":
          description: The participant or event does not exist

    put:
      tags:
        - Participant
      summary: Update participant
      description: Updates a participant of an event based on the object passed via the request body
      operationId: updateParticipant

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long
        - name: partId
          in: path
          description: The id of the participant
          required: true
          schema:
            type: number
            format: long

      requestBody: 
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'

      responses:
        "201":
          description: Participant list updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Participant"
        "400":
          description: The participant does not belong to the event
        "404":
          description: The participant or event does not exist

    delete:
      tags:
        - Participant
      summary: Delete participant
      description: Deletes a participant of an event
      operationId: deleteParticipant

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long
        - name: partId
          in: path
          description: The id of the participant
          required: true
          schema:
            type: number
            format: long

      responses:
        "200":
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        "400":
          description: The participant does not belong to the event
        "404":
          description: Event or participant not found

  /api/events/{eventId}/expenses:
    get:
      tags:
        - Expense
      summary: Get expenses of event
      description: Gets all expenses of a given event
      operationId: getEventExpenses

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long

      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Expense'
        "404":
          description: The event does not exist

    post:
      tags:
        - Expense
      summary: Create expense
      description: Creates a new Expense based on the object passed via the request body
      operationId: createExpense

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long

      requestBody: 
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Expense'

      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Expense"
        "400":
          description: The payer is null or does not belong to the event
        "404":
          description: The event or participant does not exist


  /api/events/{eventId}/expenses/{expId}:
    get:
      tags:
        - Expense
      summary: Get expense
      description: Gets a specific expense
      operationId: getExpense

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long
        - name: expId
          in: path
          description: The id of the expense
          required: true
          schema:
            type: number
            format: long

      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
        "400":
          description: The expense does not belong to the event
        "404":
          description: The participant, event, or expense does not exist

    put:
      tags:
        - Expense
      summary: Update expense
      description: Updates an expense
      operationId: updateExpense

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long
        - name: expId
          in: path
          description: The id of the expense
          required: true
          schema:
            type: number
            format: long

      requestBody: 
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Expense'

      responses:
        "201":
          description: Expense updated (in case of invalid payer, it will remain the same)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Expense"
        "400":
          description: The expense does not belong to the event
        "404":
          description: The participant, event, or expense does not exist

    delete:
      tags:
        - Expense
      summary: Delete expense
      description: Deletes a specific expense
      operationId: deleteExpense

      parameters:
        - name: eventId
          in: path
          description: The id of the event
          required: true
          schema:
            type: number
            format: long
        - name: expId
          in: path
          description: The id of the expense
          required: true
          schema:
            type: number
            format: long

      responses:
        "200":
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
        "400":
          description: The expense does not belong to the event
        "404":
          description: The participant, event, or expense does not exist


  /api/admin:
    get:
      tags:
        - Admin
      summary: Get password
      description: Prints the admin password to the terminal of the server
      operationId: getPassword

      responses:
        "200":
          description: Password printed to console

  /api/rates/{date}:
    get:
      summary: Get exchange rates
      description: For given date, get exchange rates to USD and CHF for 1 EUR
      operationId: getRates
      parameters:
        - name: date
          in: path
          description: Date to get rates for
          required: true
          schema:
            type: string
            example: 2020-03-20
      responses:
        "200":
          description: Rates retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rates'
        "400":
          description: Invalid date


components:
  schemas:
    Participant:
      type: object
      properties:
        id:
          type: number
          format: long
          example: 0
        name:
          type: string
          example: TestName
        event:
          $ref: "#/components/schemas/Event"

    Expense:
      type: object
      properties:
        id:
          type: number
          format: long
          example: 0
        amount:
          type: number
          format: double
          example: 60.00
        itemName:
          type: string
          example: TestName
        payer:
          $ref: '#/components/schemas/Participant'
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
        event:
          $ref: '#/components/schemas/Event'

    Event:
      type: object
      properties:
        id:
          type: number
          format: long
          example: 0
        name:
          type: string
          example: TestName
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
        expenses:
          type: array
          items:
            $ref: '#/components/schemas/Expense'
        creationDate:
          type: string
          format: date
          example: 2000-01-01
        lastModification:
          type: string
          format: date
          example: 2000-01-01
        inviteCode:
          type: string
          example: ABCDE12345

    Rates:
      type: object
      properties:
        usd:
          type: number
          format: double
          example: 1.07
        chf:
          type: number
          format: double
          example: 1.07