openapi: 3.0.3
info:
  title: Starnberger See API
  description: API for accessing water temperature measurements and DWD weather data.
  version: 1.0.0
servers:
  - url: /
    description: Local server
paths:
  /api/v1/latest:
    get:
      summary: Get the latest measurement
      description: Returns the single most recent temperature measurement.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/entries:
    get:
      summary: Get the last N entries
      description: Returns the last N temperature measurements.
      parameters:
        - name: limit
          in: query
          description: The number of entries to return. Must be between 1 and 128.
          required: false
          schema:
            type: integer
            default: 24
            minimum: 1
            maximum: 128
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Measurement'
        '400':
          description: Invalid limit parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/dwd:
    get:
      summary: Get latest DWD data
      description: Returns the latest DWD temperature range.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWD'
        '404':
          description: No DWD data available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Measurement:
      type: object
      required:
        - temperature
        - datetime
      properties:
        temperature:
          type: number
          description: The water temperature.
        datetime:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$'
          example: '2026-04-29T10:15:00'
          description: The timestamp of the measurement as Germany local time (Europe/Berlin), matching the NID Bayern source table.
    DWD:
      type: object
      required:
        - temperatureMin
        - temperatureMax
      properties:
        temperatureMin:
          type: number
          description: The minimum temperature from DWD.
        temperatureMax:
          type: number
          description: The maximum temperature from DWD.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: The error message.