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 your app, create a file /api.js in your app's root folder. An example is shown below.

/api.js

module.exports = [

    {
        method:         'GET',
        path:            '/',
        public:            true,
        fn: function( args, callback ){
            var result = Homey.app.getSomething();

            // callback follows ( err, result )
            callback( null, result );

            // access /?foo=bar as args.query.foo
        }
    },

    {
        method:         'POST',
        path:            '/',
        fn: function( args, callback ){
            var result = Homey.app.addSomething( args.body );
            if( result instanceof Error ) return callback( result );
            return callback( null, result );
        }
    },

    {
        method:         'PUT',
        path:            '/:id',
        fn: function( args, callback ){
            var result = Homey.app.updateSomething( args.params.id, args.body );
            if( result instanceof Error ) return callback( result );
            return callback( null, result );
        }
    },

    {
        method:         'DELETE',
        path:            '/:id',
        fn: function( args, callback ){
            var result = Homey.app.deleteSomething( args.params.id );
            if( result instanceof Error ) return callback( result );
            return callback( null, result );
        }
    }

]

Homey.app is the instance of your App.

Parameters

Possible parameters for an API endpoint object are:

key type value
method String, Array GET, POST, PUT or DELETE, or an array of these values
path String e.g. /, /:foo, /bar/:foo
fn Function The function to execute when the call has been made
public Boolean Set to true to make this endpoint accessible without a token
role String Set to owner to make this endpoint only accessible to owners

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

ManagerApi.realtime('my_event', 'my_json_stringifyable_value')
    .catch( this.error )