Your app's API endpoints are available under the following url: /api/app/com.yourapp.id/. All endpoints are protected by default, 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 Manifest. The key of each route corresponds to the name of a function defined in api.js. The following route options can be configured in the App Manifest:

In the following example we define four routes named getSomething, addSomething, updateSomething and deleteSomething:

/.homeycompose/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 is defined in the api.js file, this file should export async functions with names that correspond to the names defined in the App Manifest. For example:

/api.js
module.exports = {
  async getSomething({ homey, query }) {
    // you can access query parameters like "/?foo=bar" through `query.foo`
​
    // you can access the App instance through homey.app
    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);
  },
};

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

• homey is the Homey instance. Using this instance you can, for example, access the App instance.

• body is an object with the request body, when your request has method POST or PUT. JSON is automatically parsed.

• params is a set of strings defined in your path.

• query is a set of strings that are provided as query parameters, for example ?foo=bar will result in { "foo": "bar" }.

Realtime events

Your app can emit 'realtime' events, which are one-way events to a subscribing client, for example a browser showing a settings view page.

/app.js
const Homey = require('homey');
​
class MyApp extends Homey.App {
  async onInit() {
    await this.homey.api.realtime("my_event", "my_json_stringifyable_value");
  }
}
​
module.exports = MyApp;

Accessing the Web API of another app

Apps can also talk to each other through their API's, however you need to define the correct permissions first. Permissions for app to app communication look like this homey:app:<appId>, for example homey:app:com.athom.example or homey:app:com.yahoo.weather.

In order to communicate with another app you first need to create a ApiApp client:

/app.js
const Homey = require('homey');
​
class MyApp extends Homey.App {
  async onInit() {
    this.otherAppApi = this.homey.api.getApiApp('com.athom.otherApp');
  }
}
​
module.exports = MyApp;

The Homey Apps SDK provides some information about the app you are connecting to. For example whether it is installed on the Homey your app is installed on and what version of the app is installed. You can even subscribe to events that get emitted when an app is installed or uninstalled.

/app.js
const Homey = require('homey');
​
class MyApp extends Homey.App {
  async onInit() {
    const isInstalled = await this.otherAppApi.getInstalled();
    const version = await this.otherAppApi.getVersion();
​
    this.otherAppApi.on('install', () => {
      console.log('otherApp is installed');
    });
​
    this.otherAppApi.on('uninstall', () => {
      console.log('otherApp is uninstalled');
    });
  }
}
​
module.exports = MyApp;

You can interact with the Web API of the target app by making requests and listening to realtime events. Which APIs and events you can expect is up to the target app, so make sure to check the source code, read the documentation or ask the app's developer.

/app.js
const Homey = require('homey');
​
class MyApp extends Homey.App {
  async onInit() {
    // Make a get request to "otherApp"s API
    const getResponse = await this.otherAppApi.get('/');
​
    // Post some data to "otherApp", the second argument is the request body
    const postResponse = await this.otherAppApi.post('/play', { sound: 'bell' });
​
    // Listen to app realtime events
    this.otherAppApi.on('realtime', (event) => {
      console.log('otherApp.onRealtime', event);
    });
  }
}
​
module.exports = MyApp;