Skip to content

API

Jump to bottom
Ezequiel Holzweissig edited this page Nov 19, 2020 · 1 revision

API

This module implements since v2.0.0 a RESTful(-ish) API to control everything in your MagicMirror. With this implementation, you can use paths to modify the behavior of your mirror.

Overview

This extension exposes the /api URL from your MagicMirror² installation. Just like using the regular MMM-Remote-Control module, make sure your configuration listens on more than just localhost.

All URLs will be of the form: http://magicmirrorip:8080/api/{your command} and depending on the command, either GET or POST methods are accepted.

You can use http://magicmirrorip:8080/api/docs to see everything that's capable the API, and also test the endpoints there.

Basic examples for showing an Alert on the screen

$ curl -X GET http://magicmirrorip:8080/api/module/alert/showalert?message=Hello&timer=2000
$ curl -X POST http://magicmirrorip:8080/api/module/alert/showalert \
  -H 'content-type: application/json' \
  -d '{ 
    "title": "Hello World!", 
    "message": "Alert Successfully Shown!", 
    "timer": 2000
    }'

Basic examples of sending a Module Notification

$ curl -X GET http://magicmirrorip:8080/api/notification/HELLO_WORLD
$ curl -X POST http://magicmirrorip:8080/api/notification/HELLO_WORLD \
  -H 'content-type: application/json' \
  -d '{ 
    "mypayload": "Hello World!", 
    "somthingelse": "Wooo!"
    }'

Authentication

Providing an API key is recommended; however, remains optional. If you wish to use an API key to authenticate, add an apiKey: option to the config section for this module.

If you ran the installer.sh script when you installed the module, a non-canoical UUID is generated for you to use; you can use this unique code, or use any string you wish.

Example Config Section

{
    module: 'MMM-Remote-Control'
    config: {
        apiKey: 'bc2e979db92f4741afad01d5d18eb8e2'
    }
},

Passing your API key

The API Key can be passed in one of two ways, either as part of the query string at the end of the URL:

$ curl -X GET http://magicmirrorip:8080/api/module/alert/showalert?message=Hello&timer=2000&apiKey=bc2e979db92f4741afad01d5d18eb8e2

It can also be passed as an Authorization Header:

$ curl -X POST http://magicmirrorip:8080/api/module/alert/showalert \
  -H 'content-type: application/json' \
  -H 'Authorization: apiKey bc2e979db92f4741afad01d5d18eb8e2' \
  -d '{ 
    "title": "Hello World!", 
    "message": "Alert Successfully Shown!", 
    "timer": 2000
    }'

For convenience, the remainder of the examples omit the API Key

Secure Endpoints

Since 2.2.0, and in a way to prevent malicious actions on your mirror, a new config was added. This config allow you to, in case you don't use an apikey or never use the API at all, prevent some endpoints to work without an apikey. As usual, this option can be disabled, but this will expose your Mirror to potentials hackers, so it's up to you to turn it off.

{
    module: 'MMM-Remote-Control'
    config: {
        secureEndpoints: true
    }
},

By default, secureEndpoints it's true, defending commands like shutdown or install modules when no apikey it's present. Setting secureEndpoints to false allow every endpoint to be reachable externally, even without an apikey. (Just like the old times)

Methods

There are three general categories of API commands:

1. MMM-Remote-Control Internal Commands -- these are used to call the existing commands that MMM-Remote-Control already exposes. For example, to turn off the monitor ("MONITOROFF"):

            $ curl -X GET http://magicmirrorip:8080/api/monitor/off

2. External APIs (Guessed) -- when this module first loads, it parses all of the installed modules' source code and checks for any custom notifications that are used. From this basic search, it tries to "guess" notification actions that may be valid, without them being explicitly defined anywhere else. For example, the "alert" command examples above are not defined within this module, the 'alert' module just looks for a notification, "SHOW_ALERT"--this is exposed as a /module/alert/showalert action in the External API processor. Full credit to this idea goes to juzim from the MMM-Api module.

3. External APIs (Explicit) -- these commands are developed when a module loads and sends a "REGISTER_API" notification with command details to this module. These commands will overwrite any "guessed" commands and can provide a way for a module to define its own API, but still use the same routes already in place.

1. MMM-Remote-Control Internal Commands

The majority of MMM-Remote-Control's abilities are extended to the API (this is a fundamental reason for "extending" this module instead of creating a new one for the API).

Review the API documentation online here

Or check it in your own installation using http://ip-of-your-mirror:8080/api/docs

2. External APIs (Guessed)

As discussed above, these methods are guessed based on your currently installed modules. To see what actions are available on your particular installation:

Method URL Description
GET /api/module Return every module named inside config file, with the data of each one.
GET /api/module/:moduleName Returns the information of a given module
:moduleName: Name or Identifier for an installed & activated module.
  • NOTE: Just because an action appears in this list, does not necessarily mean it is valid and the related module will do what you want. Consult each modules' README for details on what notifications can be used and how.

Example:

$ curl -X GET http://magicmirrorip:8080/api/module/alert

Returns:

{
  "success": true,
  "data": [
    {
      "index": "0",
      "identifier": "module_0_alert",
      "name": "alert",
      "path": "modules/default/alert/",
      "file": "alert.js",
      "config": {},
      "classes": "alert",
      "hidden": false,
      "lockStrings": [],
      "actions": {
        "showalert": {
          "notification": "SHOW_ALERT",
          "guessed": true
        },
        "hidealert": {
          "notification": "HIDE_ALERT",
          "guessed": true
        }
      }
    }
  ]
}
Parameter Description
"success" Result of the GET call
"identifier" Module identifier
"name" Module name
"path" API path to use. All lower case, with "MMM-" and "-"s removed (e.g. MMM-Remote-Control's path if it had one would be /api/module/remotecontrol/). Can be customized for explicit External APIs.
"file" Principal file of the module
"config" Module configuration
"name" Module name
"hidden" If the module is hidden
"lockString" If hidden, by which module
"actions" The list of actions registered, along with the respective notifications that they will call.
For example, GET /api/module/alert/showalert will send a "SHOW_ALERT" notification to the alert module
"notification" Notification send when this action it's called.
"guessed" Whether or not the API actions were guessed (not all are reliable) or if they were explicitly provided by the module.

3. External APIs (Explicit) - Extending Another Module with this API

For module developers, you can extend the API to accomodate your needs by sending a "REGISTER_API" module notification. Below is an example and details.

If correctly formated, any details sent here will override the "guessed" action by #2 above.

let payload = {
  module: this.name, 
  path: "modulename", 
  actions: {   
    actionName: { 
        method: "GET", 
        notification: "NOTIFICATION_TO_SEND", 
        payload: ObjectToSend, 
        prettyName: "Action Name"
    },
    anotherActionName: { 
        method: "POST", 
        notification: "NOTIFICATION_TO_SEND"
    }
  }
};
this.sendNotification("REGISTER_API", payload);
Parameter Description
module Actual Name of your Module (e.g. "MMM-Your-Module-Name, or just use this.name)
path Path to use in the API (e.g. path: "mymodulename") translates to /api/module/mymodulename
actions An Object defining the actions you want to expose. See below for details.
actionName The name for your action (e.g. called from /api/module/mymodulename/actionName).
method Optional: The HTTP Method to use.
Valid options are: "GET" or "POST". If method is not provided in an action, then both "GET" or "POST" methods will be treated as valid.
notification The notification to send to your module. When the API receives a valid action, it passes a Module Notification to your module. It is your responsibility to do something with that notification to make the action work.
prettyName Optional: You can specify a Formatted Name to use in dynamic menus, like the MMM-Remote-Control Module Control menu, otherwise one will be guessed based on the Notification text.
payload Optional: If you always want the module to send the same payload, you can provide an Object here. See below for more details.

About the payload Object

Your module will be sent a payload with the notification, depending on the request details, and if you provided a payload Object to send. It is a merged object, containing one or more of the following inputs.

  1. URL Parameter. (e.g. /api/module/mymodulename/action/:p, where :p is the parameter). If nothing else below is passed or provided, this will be returned as a string. If anything else below is sent, this will be provided at payload.param in the notification's payload Object.
  2. Query String. Anything passed to the query string, except the API Key (if used) will be passed through payload. For example, /api/module/mymodulename/action?param1=Something&param2=Else will be passed in payload as { param1: "Something", param2: "Else" }
  3. POST Body. Same as query string above.
  4. Custom Payload. Any Object provided with the payload: key when you send the initial "REGISTER_API" notification.

The response sent by the API will include the payload Object it sent to your module in the response body for debugging purposes.

Clone this wiki locally