This module for the Magic Mirror² provides a somewhat RESTful(ish) API to control the behaviour of the mirror.
The code is based on the great MMM-Remote-Control module.
To send a notification to a module, just send a POST
request to
MAGIG_MIRROR_IP:PORT/api/v1/modules/MODULE_NAME/ACTION?payload1key=payload1value&payload2key=payload2value
Example:
curl -X POST 'http://localhost:3001/api/v1/modules/mmm-glance/glance_on?name=news&time=1000'
To send a global notification, use
MAGIG_MIRROR_IP:PORT/api/v1/notify/ACTION?payload1key=payload1value&payload2key=payload2value
Example:
curl -X POST 'http://localhost:3001/api/v1/notify/glance_on?name=news&time=1000'
The advantage of specifying a module is having some basic validation which helps with debugging and error handling.
Example:
curl -X POST 'http://localhost:3001/api/v1/modules/imaginary_module/do_stuff'
will return a 404 response with an error message:
{"success":"false","error":"Module not found"}
or
{"success":"false","error":"Action not found"}
Successful calls return
{"success":"true"}
The payload is passed as URL parameters. These are neither validated nor do they trigger an error message for invalid or missing keys or values.
Routes | request | description |
---|---|---|
modules | GET | get a list of all installed modules and actions:{"success": "true", "modules": {"alert": ["SHOW_ALERT","HIDE_ALERT"]} |
modules/moduleName | GET | get a list of available actions for a module:{"success":"true","actions":["SHOW_ALERT","HIDE_ALERT"]} |
modules/moduleName/action | POST | send a notification to a module |
notify/action | POST | send a global notification |
If you followed the default installation instructions for the Magic Mirror² project, you should be able to use the automatic installer. The following command will download the installer and execute it:
bash -c "$(curl -s https://raw.githubusercontent.com/juzim/MMM-Api/master/installer.sh)"
- Clone this repository in your
modules
folder, and install dependencies:
cd ~/MagicMirror/modules # adapt directory if you are using a different one
git clone https://github.com/juzim/MMM-Api.git
cd MMM-Api
npm install
- Add the module to your
config/config.js
file, if you add aposition
, it will display the URL to the remote on the mirror.
{
module: 'MMM-Api'
},
-
Add the IP addresses of devices you want to use to access the Remote Control to the
ipWhiteList
in yourconfig.js
. -
Restart your Magic Mirror² (i.e.
pm2 restart mm
).
Update this module by navigating into its folder on the command line and using git pull
:
cd ~/MagicMirror/modules/MMM-Api # adapt directory if you are using a different one
git pull
npm install # install (new) dependencies
Alternatively you can run the installer.sh
script again:
~/MagicMirror/modules/MMM-Api/installer.sh
- the list of actions is generated by pulling some assumed action names from the files and should not be relied on
- in addition the validation of modules and actions is purely cosmetic to help with debugging and error handling. Since every notification can be send with the notify command, it should not be seen as a security layer
- Return available actions/modules on errors
- Extract routes to separate files
- Look for available actions only in notificationReceived block
- (maybe) create a convention for modules to provide information about expected actions and payloads and raise errors for missing, invalid or extra data