REST Models

To facilitate the easy access to device data, the Manager utilizes REST models that provide access methods to get, find, update and manage remote device data.

A REST model adapts Javascript requests for data into HTTP requests to a backend service. The Manager REST models can communciate with cloud-based or local device backends with change.

Constructing

For each device data entity, REST models can be created using the Manager's Rest constructor. For example:

import {Rest} from 'manager'

const Port = new Rest('port')

Once constructed, the app can use the model to manage the controlled entity:

let portList = await Port.find()
let port = await Port.get({name: 'eth-00'})
await Port.remove({id: port.id})

Standard Methods

The Rest construct will create the following standard access methods:

Method	Method	URL	Description
get	POST	/:controller/get	Get a data item
find	POST	/:controller/find	Find a set of matching items
remove	POST	/:controller/remove	Remove an item
update	POST	/:controller/update	Update an item

Where :controller is replaced with the name provided to the Rest constructor. The Ioto cloud service only implements the "POST" method whereas the Ioto agent embedded web server supports all HTTP verbs.

Custom Methods

You can provide additional methods for custom methods via an additional argument to the Rest constructor.

const Port = new Rest('port', {
    rest: { method: 'POST', uri: '/:controller/reset' },
    ...
})

The Ioto embedded web server can define Action methods that connect with each of the REST model request methods via the webAddAction C API.

Hosted device clouds provide standard backend methods. So to implement custom Rest methods, you use a different technique where the logic is implemented inline in the Rest method.

Inline Custom Methods

You can provide inline methods to implement Rest methods with centralized logic for device operations.

For example:

const Port = new Rest('port', {
    reset: { invoke: async (fields) => {
        //  Custom logic
    }},
    ...
})

Tunnels Requests

Hosted device cloud requests are handled by a "Generic" cloud controller rather than individual controllers for each Rest instance.

Consequently, Rest requests are "tunneled" though the "Generic" controller. To achieve this, the tunnel mapping is specified via the Rest constructor.

const Port = new Rest('port', {}, {
    tunnel: 'Port',
})

This will tunnel Port requests to the Generic controller to access the "Port" database entity.

Adding Context

It is sometimes convenient to add application context to the Rest request properties. This can be done via the "context" property.

The context method is provided the request body properties. These can be modified to add or remove values.

The state.app.context collection stores the deviceId and other values added via the state.app.addContext method.

For example: this will add the deviceId to all requests:

const Port = new Rest('port', {},
    context: (body) => {
        body.deviceId = state.app.context.deviceId
        return body
    }
)

Rest API Properties

The Rest API method definitions can use the following properties:

Property	Description
base	Base url to use instead of the config.api
body	Post body data
clear	Clear prior feedback
feedback	If true, emit feedback on success. Default, emit only on errors.
invoke	Function to invoke instead of issuing URI request
log	Set to true to trace the request and response
method	HTTP method verb
nologout	Don't logout if response is 401
noparse	Don't json parse any JSON response
noprefix	Don't prefix the URL. Use the window.location host address.
progress	If true, show progress bar.
raw	If true, return the full response object (see below). If false, return just the data.
refresh	To control cache refresh
throw	If false, do not throw on errors
uri	URI template. Fields prefixed with ":" are expanded.