FhAPI

About

FhAPI provides a REST-like web API with user specific device authorization.

When you need this module:


• 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.

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:

• http://yourserver/fhem?cmd=set+Light+on
• http://yourserver/fhem?XHR=1&cmd=list+Light
Currently fhem can restrict web interface instances to certain commands (e.g. get only), but it cannot restrict a web interface to a limited set of devices. Devices can be hidden, but this doesn't guarantee security.

Limitations of this module:


• 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.

Example use:


• Get the state: GET https://yourserver/fhapi/Light/state/ gives on
• Get all readings: GET https://yourserver/fhapi/Light/ gives {"state":"on"}
• Set a single reading: POST on to https://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"} to https://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/ gives blue




Define

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/

Attributes

• 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, configuration and usage examples

• 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:secRet@192.168.1.1/fhapi/SomeLight/
        curl -s -d on https://switch123:secRet@192.168.1.1/fhapi/SomeLight/state
        curl -s -H 'Content-Type: application/json' -d '{"state":"off","powersave":"on"}' https://switch123:secRet@192.168.1.1/fhapi/SomeLight/state
        # Some embedded OpenWRT linux system with no space for a full-blown curl:
        wget -q -O - "http://switch123:secRet@192.168.1.1/fhapi/SomeLight/state?set=on"