rest-api.yaml

openapi: 3.0.0
info:
  version: v1
  title: Rest Api myBudget

security:
  - api-auth-token: []



paths:
  /session:
    post:
      operationId: sessionPost
      tags:
        - Session
      description: >
        Obtain AccessToken, RefreshToken and the user session
      requestBody:
        $ref: '#/components/requestBodies/LoginRequest'
        required: true
      responses:
        '201':
          description: The session object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          description: |
            Invalid credentials
        '403':
          description: |
            User not Active            

  /session/refresh/{refreshtoken}:
    post:
      operationId: sessionRefreshPost
      tags:
        - Session
      description: >
                Obtain a new AccessToken and user session using RefreshToken
      parameters:
        - name: refreshtoken
          in: path
          required: true
          schema:
            type: string
      responses:
        '201':
          description: The session object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          description: |
            Invalid Refresh Token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                
  /registration-user:
    post:
      operationId: registrationUserPost
      tags:
        - UserRegistrationInfo
      description: >
                Registrate anew User
      requestBody:
        $ref: '#/components/requestBodies/UserRegistrationInfo'
        required: true
      responses:
        '204':
          description: User Created and sent the confirm registration mail
        '400':
          description: |
            I
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'       

  /resend-confirm-registration-mail:
    post:
      operationId: resendRegistrationConfirmUserPost
      tags:
        - UserRegistrationInfo
      description: >
                Resend confirm registration mail
      parameters:
        - name: username
          in: query
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User Created and sent the confirm registration mail
        '400':
          description: |
            I
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'       
                
  /confirm-registration/{username}:
    post:
      operationId: registrationUserGet
      tags:
        - UserRegistrationInfo
      description: >
                Confirm Registration
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string      
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User Created and sent the confirm registration mail
        '400':
          description: |
            I
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'       

  /categories:
    post:
      operationId: categoryPost
      tags:
        - Category
      description: >
        Create a new category
      requestBody:
        $ref: '#/components/requestBodies/Category'
        required: true
      responses:
        '201':
          description: The Category object created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          description: Invalid session
        '498':
          description: Access token expired          
        '400':
          description: |
            I
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'          
    get:
      operationId: categoryGet
      tags:
        - Category
      description: >
        Obtain the categories to use to perform new movement
      responses:
        '200':
          description: The Category object created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        '401':
          description: Invalid session
        '498':
          description: Access token expired           
                
  /categories/{id}:
    get:
      operationId: categoryGetById
      tags:
        - Category
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      description: >
        Obtain the categoriy to use to perform new movement
      responses:
        '200':
          description: Category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '404':
          description: Category Not Found       
        '401':
          description: Invalid session
        '498':
          description: Access token expired 
          
    put:
      operationId: categoryPut
      tags:
        - Category
      description: >
        Update an existing category
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64     
      requestBody:
        $ref: '#/components/requestBodies/Category'
        required: true
      responses:
        '204':
          description: Category successfully updated
        '401':
          description: Invalid session
        '400':
          description: Unable to update category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse' 
        '404':
          description: Category Not Found             
        '498':
          description: Access token expired           
    delete:
      operationId: categoryDelete
      tags:
        - Category
      description: >
        Delete an existing category
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: Category successfully deleted
        '401':
          description: Invalid session
        '498':
          description: Access token expired           
        '400':
          description: Unable to update category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse' 
        '404':
          description: Category Not Found

  /movements:
    post:
      operationId: movementsPost
      tags:
        - Movement
      description: >
        Create a new movement
      requestBody:
        $ref: '#/components/requestBodies/Movement'
        required: true
      responses:
        '201':
          description: The Category object created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movement'
        '401':
          description: Invalid session
        '498':
          description: Access token expired          
        '400':
          description: |
            I
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: movementsGet
      tags:
        - Movement
      description: Returns paged list of Movements
      parameters:
        - name: year
          in: query
          required: true
          schema:
            type: integer 
        - name: month
          in: query
          required: true
          schema:
            type: integer 
        - name: day
          in: query
          schema:
            type: integer    
        - name: week
          in: query
          schema:
            type: integer                 
        - name: category
          in: query
          schema:
            type: integer
            format: int64
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/sizeParam'
        - $ref: '#/components/parameters/sortParam'
      responses:
        '200':
          description: The paged Movement list object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MovementListPage'
        '401':
          description: Invalid session
        '498':
          description: Access token expired
          
  /movements/{id}:
    get:
      operationId: movementsGetById
      tags:
        - Movement
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      description: >
        Obtain the movement
      responses:
        '200':
          description: Category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movement'
        '404':
          description: Movement Not Found       
        '401':
          description: Invalid session
        '498':
          description: Access token expired 
          
    put:
      operationId: movementPut
      tags:
        - Movement
      description: >
        Update an existing movement
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64     
      requestBody:
        $ref: '#/components/requestBodies/Movement'
        required: true
      responses:
        '204':
          description: Movement successfully updated
        '401':
          description: Invalid session
        '400':
          description: Unable to update movement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse' 
        '404':
          description: Category Not Found             
        '498':
          description: Access token expired           
    delete:
      operationId: movementDelete
      tags:
        - Movement
      description: >
        Delete an existing movement
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: Movement successfully deleted
        '401':
          description: Invalid session
        '498':
          description: Access token expired           
        '400':
          description: Unable to update movement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse' 
        '404':
          description: Category Not Found
          
  /expense-summary:          
    get:
      operationId: expenseSummaryGet
      tags:
        - Movement
      description: Return the expense summary
      parameters:
        - name: year
          in: query
          required: true
          schema:
            type: integer 
        - name: month
          in: query
          required: true
          schema:
            type: integer 
        - name: day
          in: query
          schema:
            type: integer
        - name: week
          in: query
          schema:
            type: integer                 
      responses:
        '200':
          description: The paged Movement list object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseSummary'
        '401':
          description: Invalid session
        '498':
          description: Access token expired          
          
servers:
  - url: 'http://api.mybudget.com/v1'

components:
  parameters:
    pageParam:
      description: The page number (zero-based index)
      name: page
      in: query
      required: true
      schema:
        type: integer
    sizeParam:
      name: size
      in: query
      description: The number of records per page
      required: true
      schema:
        type: integer
    sortParam:
      name: sort
      in: query
      required: false
      description: 'The fields to sort (example sort=field1,desc&sort=field2,asc)'
      explode: true
      schema:
        type: array
        items:
          type: string

  requestBodies:

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

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

    Movement:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Movement'        
      required: true
    UserRegistrationInfo:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserRegistrationInfo'        
      required: true      
      
  securitySchemes:
    api-auth-token:
      type: apiKey
      description: >-
        The session access token obtained on login via the /session API by
        response header x-access-token property
      in: header
      name: x-access-token
    api-refresh-token:
      type: apiKey
      description: >-
        The session refresh token obtained on login via the /session API by
        response header x-refresh-token property. Using this token to obtain a new access token
      in: header
      name: x-refresh-token

  schemas:

    Page:
      type: object
      properties:
        first:
          type: boolean
          example: true            
        last:
          type: boolean
          example: false
        size:
          type: integer
          example: 30          
        totalElements:
          type: integer
          example: 300          
        totalPages:
          type: integer
          example: 10          
        number:
          type: integer
          example: 10          
      required:
        - first
        - last
        - size
        - totalElements
        - totalPages
        - number

    ErrorInternal:
      description: Available only in the debug environment
      type: object
      properties:
        exception:
          type: string
          example: NotFoundException          
          readOnly: true
        stack:
          type: string
          example: it.italiancoders.NotfoundException line 200          
          readOnly: true
      required:
        - exception

    ErrorData:
      type: object
      properties:
        userTitle:
          description: The title for the popup error message
          type: string
          example: Updating Failed          
          readOnly: true
        userMessage:
          example: Unable to Perform the action requested        
          description: >-
            The error message to show (depending on the locale used when
            creating the session)
          type: string
          readOnly: true
        internal:
          $ref: '#/components/schemas/ErrorInternal'
          readOnly: true
        constraintErrors:
          description: if it is valued contains a list of constraints not respected in the current post/put request
          type: array
          items:
            $ref: '#/components/schemas/ConstraintError'         
      required:
        - userTitle
        - userMessage

    ConstraintError:
      type: object
      properties:
        fieldName:
          description: the field name
          type: string
          example: Name         
        constraintsNotRespected:
          description: a list of constraints Not Respected
          type: array
          items:
            type: string
          
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorData'
          readOnly: true
      required:
        - error

    UserRole:
      type: string
      enum:
        - VIEW_BUDGET
        - DELETE_EXPENSE
        - ADD_EXPENSE
        
    User:
      type: object
      properties:
        username:
          type: string
          example: admin
        email:
          type: string
          example: admin@gmail.com          
        roles:
          description: User Roles
          type: array
          items:
            $ref: '#/components/schemas/UserRole'          
          example: [VIEW_BUDGET]
      required:
        - username
        - roles
        - email
        
    UserRegistrationInfo:
      type: object
      properties:
        username:
          type: string
          example: admin
        firstname:
          type: string
          example: admin
        lastname:
          type: string
          example: admin 
        password:
          type: string
          example: admin
          minLength: 5
          maxLength: 30          
        email:
          type: string
          example: admin@gmail.com   
      required:
        - username
        - password
        - email
        
    LoginRequest:
      type: object
      properties:
        username:
          type: string
          example: admin
        password:
          type: string
          example: admin
        locale:
          type: string
          example: it
      required:
        - username
        - password

    Session:
      type: object
      properties:
        userInfo:
          $ref: '#/components/schemas/User'
        locale:
          type: string
          example: it
        environment:
          description: >-
            Environment name (could be used for external app integration or to
            be shown in UI)
          type: string
          example: teq
        accessToken:
          type: string
          example: xxxx
        refreshToken:
          type: string
          example: yyyyyyyy          
      required:
        - username
        - locale
        - accessToken
        - refreshToken

    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1      
          readOnly: true
        name:
          type: string
          example: CIBO
          minLength: 3
          maxLength: 20          
        description:
          type: string
          maxLength: 150 
          example: CIBO
        isReadOnly:
          type: boolean
          readOnly: true
          example: CIBO           
      required:
        - name

        
    Movement:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1      
          readOnly: true      
        amount:
          type: number
          format: double
          example: 2
        category:
          $ref: '#/components/schemas/Category'          
        executedAt:
          type: string
          format: date-time
        note:
          type: string
          example: xxx
          maxLength: 200            
      required:
        - amount
        - category

    CategoryMovementOverview:
      type: object
      properties:
        totalAmount:
          type: number
          format: double
          example: 2
        category:
          $ref: '#/components/schemas/Category'
      required:
        - amount
        - category
        
    ExpenseSummary:
      type: object
      properties:
        totalAmount:
          type: number
          format: double
          example: 2
        categoryOverview:
          type: array
          items:
            $ref: '#/components/schemas/CategoryMovementOverview'
        lastMovements:
          $ref: '#/components/schemas/MovementListPage'

            
    MovementListPage:
      description: Paged Movement list
      x-list-javaCustomization:
        avoidBuilder: true
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            contents:
              type: array
              items:
                $ref: '#/components/schemas/Movement'
          required:
            - contents