Module millheat
Millheat API library for Millheat electrical heaters.
This library implements the session management and makes it easy to access individual endpoints of the API.
API documentation: http://mn-be-prod-documentation.s3-website.eu-central-1.amazonaws.com/#/.
Usage:
local millheat = require "millheat" local mhsession = millheat.new { -- use username/password OR apikey, not both! username = "name@email.org", password = "secret_password", -- api_key = "xyz", } local ok, data = self:srequest("GET:/houses/{houseId}/rooms", { houseId = "some-id-here" }) if not ok then print("failed to get rooms: ", data) end mhsession:logout()
-- or using the Copas scheduler local copas = require "copas" copas.addthread(function() local millheat = require "millheat" local mhsession = millheat.new { -- use username/password OR apikey, not both! username = "name@email.org", password = "secret_password", -- api_key = "xyz", } local ok, data = self:srequest("GET:/houses/{houseId}/rooms", { houseId = "some-id-here" }) if not ok then print("failed to get rooms: ", data) end mhsession:logout() end) copas.loop()
Info:
- Copyright: 2020-2024 Thijs Schreijer
- Release: Version 0.4.1, Library to access the Millheat API
- License: millheat.lua is free software under the MIT/X11 license.
- Author: Thijs Schreijer
Tables
millheat | The module table containing some global settings and constants. |
Generic functions
login () | Logs in the current session. |
logout (clear) | Logs out of the current session. |
new (opts) | Creates a new Millheat session instance. |
request (path[, method="GET"[, query[, body]]]) | Performs a HTTP request on the Millheat API. |
rewrite_error ([expected], ...) | Rewrite errors to Lua format (nil+error). |
srequest (path[, params[, body]]) | Smart HTTP request on the Millheat API. |
API specific functions
get_houses () | Gets the list of houses. |
Tables
- millheat
-
The module table containing some global settings and constants.
Fields:
- https
This is a function set on the module table, such that it can
be overridden by another implementation. If Copas) was
loaded before this module then
copas.http
will be used, otherwise it uses the LuaSec one (modulessl.https
). - log Logger is set on the module table, to be able to override it. Default is the LuaLogging default logger if LuaLogging was loaded before this module. Otherwise it uses a stub logger with only no-op functions.
- https
This is a function set on the module table, such that it can
be overridden by another implementation. If Copas) was
loaded before this module then
Generic functions
Functions for session management and instantiation
- login ()
-
Logs in the current session.
This will automatically be called by the request and srequest methods, if
not logged in already. Has no effect for API key auth.
Returns:
true
ornil+err
Usage:
local millheat = require "millheat" local mhsession = millheat.new { username = "name@email.org", password = "secret_password", } local ok, err = mhsession:login() if not ok then print("failed to login: ", err) end
- logout (clear)
-
Logs out of the current session.
This only applies to user/pwd login. Does nothing for API key auth.
Parameters:
- clear bool if truthy, the current session is removed from the session cache, and the next call to millheat.new will create a new session instead of reusing the cached one.
Returns:
true
ornil+err
Usage:
local millheat = require "millheat" local mhsession = millheat.new { username = "name@email.org", password = "secret_password", } local ok, err = mhsession:login() if not ok then print("failed to login: ", err) else mhsession:logout() end
- new (opts)
-
Creates a new Millheat session instance.
If a session for the credentials already exists, the existing session is
returned. See millheat.logout for destroying sessions.
Use either
username+password
ORapi_key
, not both.Parameters:
- opts the options table, supporting the following options:
Returns:
-
Millheat session object
Usage:
local millheat = require "millheat" local mhsession = millheat.new { username = "name@email.org", password = "secret_password", } local ok, err = mhsession:login() if not ok then print("failed to login: ", err) end
- request (path[, method="GET"[, query[, body]]])
-
Performs a HTTP request on the Millheat API.
It will automatically inject authentication/session data. Or if not
logged in yet, it will log in. If the session has expired it will be renewed.
This method is a low-level method, and is used by the higher level srequest. The latter is recommended for use in most cases since it is easier to use and more readable.
NOTE: if the response_body is JSON, then it will be decoded and returned as a Lua table.
Parameters:
- path string the relative path within the API base path
- method string the http method to use (will be capitalized) (default "GET")
- query table query parameters (will be escaped) (optional)
- body table or string request body, a table will be encoded as json (optional)
Returns:
ok
,response_body
,response_code
,response_headers
,response_status_line
Usage:
local millheat = require "millheat" local mhsession = millheat.new { username = "name@email.org", password = "secret_password", } local body = { param1 = "value1" } -- the following line will automatically log in local ok, response_body, status, headers, statusline = mhsession:request("/some/path", "GET", nil, body)
- rewrite_error ([expected], ...)
-
Rewrite errors to Lua format (nil+error).
Takes the output of the request function and validates it for errors;
- nil+err
- mismatch in expected status code (a 200 expected, but a 404 received)
This reduces the error handling to standard Lua errors, instead of having to validate each of the situations above individually.
Parameters:
- expected
number or table
expected status code, if
nil
, it will be ignored. If a table then the keys must be the allowed status codes. (optional) - ... same parameters as the request method
Returns:
nil+err
on error, or the input argumentsUsage:
local millheat = require "millheat" local mhsession = millheat.new { username = "name@email.org", password = "secret_password", } -- Make a request where we expect a 200 or 201 result expected = { 200 = true, 201 = true } local ok, response_body, status, headers, statusline = mhsession:rewrite_error(expected, mhsession:request("/some/path")) if not ok then return nil, response_body -- a 404 will also follow this path now, since we only want 200's end
- srequest (path[, params[, body]])
-
Smart HTTP request on the Millheat API.
It will automatically inject authentication/session data, and login if required.
Parameters will be injected in the path, remaining ones will be added to the query.
Responses in
20x
range will be valid, anything else is returned as a Lua error.Parameters:
- path
string
the relative path within the API base path, format:
"METHOD:/path/{param1}/to/{param2}"
. Method defaults to "GET". - params table parameters, path parameters will be injected, others will be added to the query (they will be escaped). (optional)
- body table or string request body, a table will be encoded as json (optional)
Returns:
ok
,response_body
,response_code
,response_headers
,response_status_line
ornil+error
Usage:
local millheat = require "millheat" local mhsession = millheat.new { username = "name@email.org", password = "secret_password", } local house_id = "xyz some id" -- the following line will automatically log in, and fetch the data local ok, data = mhsession:srequest("GET:/houses/{houseId}/devices", { houseId = house_id, }) if not ok then print("failed to get devices: ", data) end
- path
string
the relative path within the API base path, format:
API specific functions
This section contains functions that directly interact with the Millheat API.