Web API

An app can hook into the Web API (REST + Realtime), to allow for external access. A use case would for example be a Raspberry PI that reports it's status to Homey.

Your app's API edpoints are available under the following url: /api/app/com.yourapp.id/. All endpoints are by default protected, and the requesting user needs permission to your app (which is granted by default after installation). You can override this by setting public: true.

To add API endpoints to an app, start by defining the routes in the app.json. The key of each route corresponds to the name of a function defined in api.json. The following route options can be configured in app.json:

For example we define four routes named getSomething, addSomething, updateSomething and deleteSomething:

/app.json

  ...
  "api": {
    "getSomething": {
      "method": "get",
      "path": "/"
    },
    "addSomething": {
      "method": "post",
      "path": "/"
    },
    "updateSomething": {
      "method": "put",
      "path": "/:id"
    },
    "deleteSomething": {
      "method": "delete",
      "path": "/:id"
    },
  },
  ...

The implementation of each route lives in the api.js file, this file should export async functions with names that correspond to the names defined in the app.json manifest. For example:

/api.js

module.exports = {
  async getSomething({ homey, query }) {
    // you can access query parameters like `/?foo=bar` through args.query.foo

    const result = await homey.app.getSomething();

    // perform other logic like mapping result data

    return result;
  },

  async addSomething({ homey, body }) {
    // access the post body and perform some action on it.
    return homey.app.addSomething(body);
  },

  async updateSomething({ homey, params, body }) {
    return homey.app.updateSomething(params.id, body);
  },

  async deleteSomething({ homey, params }) {
    return homey.app.deleteSomething(params.id);
  },
};

it is possible to access the App instance through homey.app.

Api functions receive an object as their argument, this object has four properties: homey, params, query and body.

Homey

This is the Homey instance, through this instance it is possible to, for example, access the App instance.

Body

This is an object with the body, when your request has method post or put. JSON is automatically parsed.

Params

The params object is a set of strings defined in your path.

Query

The params object is a set of strings that are provided as query parameters, e.g. ?foo=bar will result in { "foo": "bar" }.

Realtime

Your app can emit 'realtime' events, which are one-way events to a subscribing client, e.g. a browser showing a Settings page.

/app.js

this.homey.api.realtime('my_event', 'my_json_stringifyable_value').catch(this.error);