openapi: 3.0.2

info:
  title: REST-API der "Spitzenlast-Ampel"
  version: 1.0.0-alpha2
  description:
    Beschreibung des Rest-APIs der Funktionalität "Spitzenlast-Ampel" des Energiemonitors
  contact:
    name: Solarautonomie GmbH
    url: "https://www.solarautonomie.de"
    email: info@solarautonomie.de
  
servers:
  - url: http://__IP_des_Energiemonitors__:8080/peakload/v1

paths:
  /version:
    get:
      summary: Gibt die aktuelle Version des APIs zurück
      responses:
        '200':
          description:
            Die detaillierte Version des APIs in der Form "major.minor.patchlevel"
            mit einer optionalen Erweiterung nach einem '-'
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: 1.0.0-pre2

  /channels:
    get:
      summary: Gibt die Liste aller Spitzenlast-Ampeln zurück
      responses:
        '200':
          description: Eine Liste aller Spitzenlast-Ampeln
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelList"
        '500':
          description: Interner Fehler
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /info/{channelname}:
    get:
      tags:
        - Information
      summary: Gibt all Information der aktuellen Messperiode zurück
      parameters:
        - in: path
          name: channelname
          schema:
            type: string
          required: true
          description: Der Name der Spitzenlast-Ampel
      responses:
        '200':
          description: Die Informationen zur aktuellen Messperiode
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Info"
        '404':
          description: Name der Spitzenlast-Ampel unbekannt
        '500':
          description: Interner Fehler
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"

components:
  schemas:
    InternalError:
      type: object
      properties:
        reason:
          type: string
          description: Die Fehlerursache
          enum:
            - "Configuration invalid"
            - "Database access error"
    ChannelList:
      type: object
      properties:
        channels:
          type: array
          items:
            description: Name der Spitzenlast-Ampel
            type: string
    LoadState:
      description: Status der Spitzenlast-Ampel
      type: string
      enum:
        - invalid
        - red
        - yellow
        - green
      example: red
    Info:
      type: object
      properties:
        time:
          type: string
          format: date-time
        curr_period:
          type: object
          properties:
            state:
              description: Status der aktuellen Messperiode
              type: string
              enum:
                - "OK"
                - "Sync pulse timeout"
                - "No energy consumption"
            loadstate:
              $ref: "#/components/schemas/LoadState"
            starttime:
              type: string
              format: date-time
              description: Startzeitpunkt des aktuellen Messfensters
            curr_power:
              type: number
              format: double
              description: Aktuelle Leistung für das Synchronintervall
            curr_counter:
              type: number
              format: double
              description: Fortlaufender aktuellerZählerstand des unterliegenden Messkanals (S0)
        maximum:
          type: object
          properties:
            starttime:
              type: string
              format: date-time
              description: Startzeitpunkt Betrachtungszeitraum (Quartalsbeginn, Jahresbeginn oder festes Datum)
            state:
              type: string
              enum:
                - "OK"
                - "No value available"
            curr_period:
              type: number
              format: double
              description: Aktuelle Leistung für den Betrachtungszeitraum (max. Leistung im Quartal)
            treshold:
              type: number
              format: double
              description: feste Schwelle (Warn-, Fehlerschwelle) für den Betrachtungszeitraum (0 für inaktiv)
            activatethreshold:
              type: number
              format: double
              description: Schwelle Aktivierung Warn-, Fehlermeldung. Von Bedeutung am Anfang des Betrachtungszeitraums wenn keine feste Schwelle gesetzt ist
            reference_period:
              type: string
              enum:
                - "Quarter"
                - "Year"

