openapi: 3.0.3
info:
  title: Personal Finance - OpenAPI 3.0
  description: |
    Personal Finance Server
  contact:
    email: finance@murta.dev
  license:
    name: GNU General Public License v3.0 or later
    url: https://www.gnu.org/licenses/gpl-3.0-standalone.html
  version: 0.1.0

paths:
  /transactions:
    get:
      summary: Retrieve existing transactions
      operationId: getTransactions
      parameters:
        - name: category
          in: query
          description: filter by transaction category
          schema:
            $ref: "#/components/schemas/CategoryName"
            nullable: true
        - name: limit
          in: query
          description: number of transactions to return
          schema:
            type: integer
            format: int32
            default: 100
            minimum: 0
        - name: offset
          in: query
          description: offset from where to retrieve transactions
          schema:
            type: integer
            format: int32
            default: 0
            minimum: 0
        - name: bank
          in: query
          description: ID of the bank
          schema:
            type: string
        - name: sort
          in: query
          description: field name by which to sort
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transactions"
          headers:
            X-Total-Count:
              description: Total number of transactions
              schema:
                type: integer
        "204":
          description: No transactions
    post:
      summary: Create a new transaction
      operationId: createTransaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Transaction"
      responses:
        "201":
          description: Transaction created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "400":
          description: Transaction not created

  /transactions/{transactionId}:
    get:
      summary: Find transaction by ID
      operationId: getTransactionById
      parameters:
        - name: transactionId
          in: path
          description: ID of transaction to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transaction"
        "400":
          description: Invalid ID supplied
        "404":
          description: Transaction not found
    put:
      summary: Update an existing transaction
      operationId: updateTransaction
      parameters:
        - name: transactionId
          in: path
          description: ID of transaction to update
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                category:
                  $ref: "#/components/schemas/CategoryName"
      responses:
        "204":
          description: Transaction updated successfully
        "400":
          description: Nothing to update
        "404":
          description: Transaction not found

  /banks:
    get:
      summary: Retrieve existing banks
      operationId: getBanks
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Banks"
        "204":
          description: No banks

  /banks/{bankId}:
    get:
      summary: Find bank by ID
      operationId: getBankById
      parameters:
        - name: bankId
          in: path
          description: ID of bank to return
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bank"
        "400":
          description: Invalid ID supplied
        "404":
          description: Bank not found

  /categories:
    get:
      summary: Retrive existing categories
      operationId: getCategories
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Category"
        "204":
          description: No categories

components:
  schemas:
    Transaction:
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 0
        date:
          type: string
          format: date
        description:
          type: string
        value:
          type: number
          format: float
        category:
          $ref: "#/components/schemas/CategoryName"
      required:
        - date
        - description
        - value
    Transactions:
      type: array
      items:
        $ref: "#/components/schemas/Transaction"
    Bank:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        nordigenId:
          type: string
          format: uuid
      required:
        - id
        - name
    Banks:
      type: array
      items:
        $ref: "#/components/schemas/Bank"
    CategoryName:
      type: string
    Category:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/CategoryName"
        group:
          $ref: "#/components/schemas/CategoryGroup"
      required:
        - name
    CategoryGroup:
      type: object
      properties:
        name:
          type: string
      required:
        - name