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
:
key | type | value |
---|---|---|
method | String , Array |
[required] get , post , put or delete , or an array of these values |
path | String |
[required] e.g. / , /:foo , /bar/:foo |
public | Boolean |
Set to true to make this endpoint accessible without a token |
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);