openapi: 3.1.0
info:
  title: UPowr Energy Profile API
  version: 1.0.0
servers:
  - url: /api/v1/energy-profiles
security:
  - session: []
paths:
  /:
    post:
      summary: Create a new energy profile
      operationId: createEnergyProfile
      security:
        - session:
            - energy-profile:create
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateEnergyProfile'
      responses:
        '201':
          $ref: '#/components/responses/CreateResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/UnknownError'
  /{energyProfileId}:
    patch:
      summary: Update an existing energy profile
      operationId: updateEnergyProfile
      security:
        - session:
            - energy-profile:update
      parameters:
        - $ref: '#/components/parameters/energyProfileId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpdateEnergyProfile'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/UnknownError'
    delete:
      summary: Delete an existing energy profile
      operationId: deleteEnergyProfile
      security:
        - session:
            - energy-profile:delete
      parameters:
        - $ref: '#/components/parameters/energyProfileId'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/UnknownError'
components:
  parameters:
    energyProfileId:
      name: energyProfileId
      in: path
      description: The Energy Profile ID
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    CreateEnergyProfile:
      type: object
      properties:
        title:
          type: string
          description: The title of the energy profile
        tags:
          type: array
          description: A list of tags for filtering purposes
          items:
            type: string
        file:
          type: string
          format: binary
          description: CSV file to be uploaded containing energy profile data
        startYear:
          type: number
          description: Year of when when the interval energy profile data starts
        intervalMin:
          type: number
          description: Interval length in minutes for the energy profile data
        timezone:
          type: string
          description: Timezone of the site where the energy profile data was generated
      required:
        - title
        - startYear
        - intervalMin
        - timezone
        - file
    UpdateEnergyProfile:
      type: object
      properties:
        title:
          type: string
          description: The title of the energy profile
        tags:
          type: array
          description: A list of tags for filtering purposes
          items:
            type: string
        file:
          type: string
          format: binary
          description: CSV file to be uploaded containing energy profile data
        startYear:
          type: number
          description: Year of when when the interval energy profile data starts
        intervalMin:
          type: number
          description: Interval length in minutes for the energy profile data
        timezone:
          type: string
          description: Timezone of the site where the energy profile data was generated
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A message describing the error that occurred.
      required:
        - message
  responses:
    CreateResponse:
      description: Energy Profile created successfully.
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                description: The unique identifier for the newly created Energy Profile.
                format: uuid
            required:
              - id
          examples:
            actionCompleted:
              description: Energy Profile created
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa7
    SuccessResponse:
      description: Energy Profile actioned successfully.
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
                description: Indicates whether the action was successful.
            required:
              - ok
          examples:
            deleteSuccessful:
              description: Energy Profile actioned
              value:
                ok: true
    UnknownError:
      description: Unknown Error has occurred
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: A message describing the error that occurred.
            required:
              - message
          examples:
            unknownError:
              summary: Unknown error occurred
              value:
                message: >-
                  Something's gone wrong, but we've been notified and we're
                  looking into it. If you have any questions, email
                  support@upowr.com.au with the error ID:
                  3fa85f64-5717-4562-b3fc-2c963f66afa7
    BadRequestError:
      description: Bad Request Error has occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            badRequestError:
              summary: Bad Request error occurred
              value:
                message: Invalid Site Class
    UnauthorizedError:
      description: Unauthorized access. Valid authentication credentials are required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidCredentials:
              summary: Authentication failed due to invalid credentials
              value:
                message: Unauthorized
  securitySchemes:
    session:
      type: oauth2
      description: Machine-to-Machine Authorization
      flows:
        clientCredentials:
          tokenUrl: https://id.core.upowr.cloud/oauth/token
          scopes:
            energy-profile:create: Create an energy profile
            energy-profile:update: Update an energy profile
            energy-profile:delete: Delete an energy profile
