-
About
- You have different embedded devices acting as sensors/actors out there and they need to get or set readings via http(s)
- You don't want to distribute a common fhem password that can be used to execute arbitrary fhem commands
- You want control and restrict what can be done by a user
- You want a clear and REST-like access to your device using hierarchical urls.
http://yourserver/fhem?cmd=set+Light+on
http://yourserver/fhem?XHR=1&cmd=list+Light
- This module does only authorization, i.e. limit per user access to a given list of devices.
- This module does not do authentication, i.e. check a users password. You need a frontend webserver or reverse web proxy like nginx to do this.
- Additional limitations by the underlying web server implementation FHEMWEB:
- PUT and DELETE methods are not supported.
- The content-type request header is ignored.
- Avoid having a "&" within the URL: FHEMWEB uses a "&" to mark the beginning of the POST body. Be aware that some implementations automatically add fields, e.g. jQuery might add "&_=1234567" to prevent caching!
- So this interface is not 100% RESTful.
- Get the state: GET
https://yourserver/fhapi/Light/state/
giveson
- Get all readings: GET
https://yourserver/fhapi/Light/
gives{"state":"on"}
- Set a single reading: POST
on
tohttps://yourserver/fhapi/Light/state/
- Set a single reading (alternative method for clients that do not support POST): GET
https://yourserver/fhapi/Light/state/?set=on
- Trigger an event: GET
https://yourserver/fhapi/Light/state/?trigger=timer
causes a "trigger Light timer" - Set multiple readings at once: POST
{"state":"on","color":"blue"}
tohttps://yourserver/fhapi/Light/
- Get all readings: GET
https://yourserver/fhapi/Light/
gives{"state":"on","color":"blue"}
- Get a single reading: GET
https://yourserver/fhapi/Light/color/
givesblue
- userHeader
optional: Inherit (and trust!) the authenticated username from your frontend webserver in the given HTTP header.
default: use allowedCommands (get/set/trigger) and allowedDevices from the allowed device valid for the corresponding web instance. - <username>_RDevices
optional: Comma-separated List of devices that the user <username> is allowed to read, i.e. perform GET on its readings. May contain regular expressions that match on several device names.
example:attr webapi sensor1_RDevices MainDoor,.*Light
(only used if userHeader is set) - <username>_RWDevices
optional: Comma-separated List of devices that the user <username> is allowed to read and write, i.e. perform GET and POST on its readings. May contain regular expressions.
example:attr webapi sensor1_RWDevices Sensor1,OutsideLight
(only used if userHeader is set) - <username>_Response
optional:Answer to POST requests from this device. The default response is "OK".
example:attr webapi sensor1_Response !cfg.power_timeout=10000
(only used if userHeader is set) - defaultRDevices
optional: Comma-separated List of devices that all users are allowed to read.
example:attr webapi defaultRDevices OutsideTemperature
(only used if userHeader is set) - defaultRWDevices
optional: Comma-separated List of devices that all users are allowed to read and write.
notice: if you just want a RESTful interface without user limitations, you might only set defaultRDevices and defaultRWDevices.
(only used if userHeader is set) - Installation:
In order to install FhAPI just copy the perl module into your FHEM modules directory (distribution specific), e.g.:cp 98_FhAPI.pm /opt/fhem/FHEM/
- FHEM configuration:
define webapi FhAPI api attr webapi userHeader X-Remote-User attr webapi defaultRDevices OutsideTemperature attr webapi sensor1_RDevices MainDoor,.*Light attr webapi sensor1_RWDevices Sensor1 defmod WEBapi FHEMWEB 8084 global attr WEBapi csrfToken none attr WEBapi webname apifhem defmod allowed_WEBapi allowed attr allowed_WEBapi allowedCommands , attr allowed_WEBapi allowedDevices , attr allowed_WEBapi basicAuth dXNlcjpwYXNzd29yZA== attr allowed_WEBapi validFor WEBapi
- Nginx frontend configuration:
location /fhapi { auth_basic_user_file /etc/nginx/conf/htpasswd_fhapi; # generate: echo -n 'user:password'|base64 proxy_set_header Authorization "Basic dXNlcjpwYXNzd29yZA=="; proxy_pass 'http://127.0.0.1:8084/apifhem/api'; proxy_set_header X-Remote-User $remote_user; }
- Accessing the Web API:
# Secure access using cURL: curl -s https://switch123:[email protected]/fhapi/SomeLight/ curl -s -d on https://switch123:[email protected]/fhapi/SomeLight/state curl -s -H 'Content-Type: application/json' -d '{"state":"off","powersave":"on"}' https://switch123:[email protected]/fhapi/SomeLight/state # Some embedded OpenWRT linux system with no space for a full-blown curl: wget -q -O - "http://switch123:[email protected]/fhapi/SomeLight/state?set=on"
FhAPI provides a REST-like web API with user specific device authorization.
When you need this module:
Comparison to standard FHEM web interface:
You don't need this module, if it is sufficient for you to execute
plain fhem commands via HTTP:
Limitations of this module:
Example use:
define <name> FhAPI <basepath>
This module provides a REST-like web API with user specific device authorization at <fhembaseurl>/<basepath>
Example:
define webapi FhAPI api
This exposes your API instance webapi at http://yourserver/fhem/api/
Installation, configuration and usage examples