pyHeatpump/docs/openapi.yaml

openapi: "3.0.0"
info:
    title: PyHeatpump API specifications
    version: 0.1.0
paths:
    /:
        get:
            operation: get_specs
            summary: List API specs (read this file)
            responses:
                '200':
                    description: 200 response
                    content:
                        application/json:
                            examples:
                                value:
                                    [route1, route2, ..., routeN]
    /config:
        get:
            operation: get_config
            summary: Retrieves current configuration values
            responses:
                '200':
                    description: The dictionary of configuration
                    content:
                        application/json:
                            examples:
                                configuration:
                                    heatpump:
                                        option: value
                                    supervisor:
                                        option: value
                '500':
                    description: Failed to get configuration


        post:
            operation: set_config
            summary: Sets the configuration values
            content:
                application/json:
                    examples:
                        valuesToSet:
                            heatpump:
                                database: memory
                            supervisor:
                                scheme: https
                                host: supervision.gteo.fr:8081

                text/plain:
                    examples:
                        valuesToSet: heatpump.serial_port=/dev/serial0


            responses:
                '200':
                    description: Setting configuration succeeded
                '403':
                    description: Setting configuration forbidden
                '404':
                    description: Specified setting does not exists
                '415':
                    description: Sent data cannot be treated

    /config/mac_address:
        get:
            operation: get_mac_address
            summary: Retrieves current mac address (in the configuration)
            responses:
                '200':
                    description: The mac address value
                    content:
                        text/plain:
                            examples: 00:11:22:33:44:55
        post:
            operation: set_mac_address
            summary: Sets current mac address (in the configuration)
            content:
                text/plain:
                    description: If empty, sets to machine current mac
                    examples:
                        ff:ee:dd:cc:bb:aa
            responses:
                '200':
                    description: The mac address value
                    content:
                        examples: 00:11:22:33:44:55

    /config/last_update:
        get:
            operation: get_last_update
            summary: Retrieves heatpump.last_update current value (in the configuration)
            responses:
                '200':
                    description: The last update timestamp 
                    content:
                        text/plain:
                            examples: 00:11:22:33:44:55
        post:
            operation: set_last_update
            summary: Sets heatpump.last_update value (in the configuration)
            content:
                text/plain:
                    description: If 0, sets to current time
                        If < 0, sets to +x seconds
                        If > 0, sets to -x seconds
                    examples:
                        0
            responses:
                '200':
                    description: The last_update timestamp
                    content:
                        examples: 1600205650


    /variable_types:
        get:
            operation: get_variable_types
            summary: Retrieves the list of variable types and their parameters
            responses:
                '200':
                    description: The variable types details, as described in the database tab var_types
                    content:
                        application/json:
                            examples:
                                variableTypes:
                                    analog:
                                        slabel: A
                                        type: float
                                        start_address: 0
                                        end_address: 250
                                    integer:
                                        slabel: I
                                        type: int
                                        start_address: 0
                                        end_address: 250
                                    digital:
                                        slabel: D
                                        type: boolean
                                        start_address: 0
                                        end_address: 250
        set:
            operation: set_variable_types
            summary: Retrieves the list of variable types and their parameters
            content:
                application/json:
                    examples:
                        variableTypes:
                            analog:
                                slabel: A
                                type: float
                                start_address: 0
                                end_address: 250
                            integer:
                                slabel: I
                                type: int
                                start_address: 0
                                end_address: 250
                            digital:
                                slabel: D
                                type: boolean
                                start_address: 0
                                end_address: 250
             responses:
                '200':
                    description: The variable types details were correctly set.


    /variables:
        get:
            operation: get_variables
            summary: Retrieves a list of variables, by type
            parameters:
                changed:
                    description: List only variables where values changed since last fetch
                errored:
                    description: Listen only variables that the program was unable to fetch
            responses:
                '200':
                    application/json:
                        description: List of the variables
                        examples:
                            variablesList:
                                A:
                                    - 42: 34
                                    - 24: 43
                                I:
                                    - 4200: 777

        post:
            operation: set_variables
            summary: Make changes to some variables
            content:
                application/json:
                    description: List of the changes to make
                    examples:
                        variablesToSet:
                            A:
                                42: 34
                                24: 43
                            I:
                                4200: 777
                            D:
                                100: 1
                                200: 0
            responses:
                '500':
                    description: Some variables cannot be set
                    content:
                        examples:
                            variablesErrored:
                                A:
                                    - 42
                                    - 24
                                I:
                                    - 4200
                                    - 420