fcom

API

Unless otherwise stated all calls have to be authenticated. This can be done either by a normal authentication cookie of MVC or by specifying a headere named "X-API-Key" that contains a valid key that was obtained using a call to generate an API key.

Authentication API

Register User

POST /api/v1/auth/Register

Register user and login with the system.

Input

The input parameters are provided as a JSON object in the payload (And you must specify the application/json content type in the request).

Output

JSON object with the following field.

Permissions

This call can be used without being authenticated.

Generate API Key

POST /api/v1/auth/generate

Generate an API key for further API calls.

Input

The input parameters are provided as a JSON object in the payload (And you must specify the application/json content type in the request).

API keys are valid indefinitely or until a user explicitly deletes them. An applicaation must not create a new API key every time it is started, but must cache a generated API key and reuse it.

Output

JSON object with the following field.

Permissions

This call can be used without being authenticated. If authenticated you can make this call without specifying username and password to generate an additional key.

Update API Key

PUT /api/v1/auth/update

Update token information for an API key.

Input

The input parameters are provided as a JSON object in the payload (And you must specify the application/json content type in the request).

Output

If successful a simple message saying the key has been updated.

Permissions

Need to be authenticated using the api key that you wish to update.

List API Keys

GET /api/v1/auth/list

List all generated API keys for the currently authenticated user.

Input

This call takes no parameters

Output

A JSON array with the list of keys generated for the account. Each object has the following fields.

Permissions

Just need to be authenticated.

Delete API Key

DELETE /api/v1/auth/delete/{id}

Delete an API key

Input

All fields are specified on the path for the request.

Output

If successful a simple message saying the key has been deleted.

Permissions

Need to be authenticated as the user which the key belongs to.

Location API

Create Location

POST /api/v1/location/create

Create a New Location.

Input

The input parameters are provided as a JSON object in the payload (And you must specify the application/json content type in the request).

Output

JSON object describing the new object being created. Is basically the same as what is being passed in, with the addition of a location id that you will need to later attach devices or configurations to it.

Permissions

To create a location without a parent you need to have user with the Administration flag set. If you add a location with a parentId specified you need ADMIN permission on the parent location.)

Update Location

PUT /api/v1/location/update/{id}

Update a Location.

Input

The input parameters are provided as a JSON object in the payload (And you must specify the application/json content type in the request). The one exception being the location id which is provided in the path.

Output

JSON object describing the location updated. Is basically the same as what is being passed in.

Permissions

To have parentId be empty you need to have user with the Administration flag set. If you add a location with a parentId specified you need ADMIN permission on the parent location. You also need admin permission on the location itself as it is being edited.

List Locations

GET /api/v1/locations/list/{id}

List the available locations.

Input

The only parameter is an optional parameter to specify which parent location id to list children of. If not specified will list all top level locations that the current user has access to.

Output

A JSON array with the list of locations. Each object has the following fields.

Permissionns

You need ACCESS permissions to list locations.

Get Location

GET /api/v1/locations/get/{id}

Get a location.

Input

The only parameter is a parameter to specify which location id to get.

Output

A JSON object with the location. It has the following fields.

Permissionns

You need ACCESS permissions to location.

Delete Location Connfiguration

DELETE /api/v1/location/delete/{id}

Delete a specific location.

Input

The input parameters are provided on the path.

Output

A simple message indicating that the location has been deleted.

Permissions

Requires ADMIN permission on the location being deleted. Also required that the location has no child locations or devices tied to it.

Permission API

Permissions are tied to a location. Permissions are inherited down from parent location to any of its children. Currently the following permissions are used.

Finally an owner of a location (Which is the user that created the top level location) always has unrevocable ADMIN access to it.

Grant Permission

POST /api/v1/permission/grant/{id}?userName={userName}&permission={permission}

Grant a permission to a specific location.

Input

All input parameters are query parameters except for the id of the location. All fields are also required.

Output

If successful a simple message saying the permission has been granted.

Permissions

You need ADMIN permissions for the location being manipulated.

Revoke Permission

DELETE /api/v1/permission/revoke/{id}?userName={userName}&permission={permission}

Revoke a permission from a specific location.

Input

All input parameters are query parameters except for the id of the location. All fields are also required.

Output

If successful a simple message saying the permission has been revoked.

Permissions

You need ADMIN permissions for the location being manipulated.

List Permissions

GET /api/v1/permission/list/{id}

List all permission granted for a location.

Input

The only parameter is the location id for which to list permissions.

Output

A JSON array with the list of locations. Each object has the following fields.

Permissions

You need ADMIN permissions for the location being listed.

Configuration API

Configurations are used to define how the devices should behave. Configurations can be tied to either a location or a device.

Each configuration can choose which of the fields it should apply. When determining the final configuration to apply to a specific device the configurations are iterated through a specific order and only fields not specified by a previous config will be applied to the resulting configuration.

Each step goes through all the configurations from the device ID first and then the location it is tied to, followed by any parents of the location until the root is reached.

The order in which configurations arae iterated are as follows.

Create or Update Location Configuration

PUT /api/v1/configuration/location/{id}?alarmFlags={alarmFlags}&deviceType={deviceType}

Create or update the configuration for a specific location, device type and alarm type.

Input

The input parameters are provided as a JSON object in the payload (And you must specify the application/json content type in the request) except for id specified in the path and alarmFlags specified in the query string. All parameters are optional except for id.

Output

A simple message indicating that the configuration has been updated.

Permissions

Requires ADMIN permission on the location being updated.

Delete Location Connfiguration

DELETE /api/v1/configuration/location/{id}?alarmFlags={alarmFlags}&deviceType={deviceType}

Delete a specific configuation setting.

Input

The input parameters are provided as either query strings or path parameters.

Output

A simple message indicating that the configuration has been deleted.

Permissions

Requires ADMIN permission on the location being updated.

List Location Configurations

GET /api/v1/configuration/location/{id}

List configurations for a specific location.

Input

The only input parameter is specified in the path.

Output

A JSON array with the list of keys generated for the account. Each object has the following fields.

Permissions

Requires ACCES permission on the location being listed.

List Location Configuration Overrides

GET /api/v1/configuration/locationoverride/{id}

List configuration overrides for a specific location.

Input

The only input parameter is specified in the path.

Output

A JSON array with the list of keys generated for the account. Each object has the following fields.

Permissions

Requires ACCES permission on the location being listed.

Create or Update Device Configuration

PUT /api/v1/configuration/device/{id}?alarmFlags={alarmFlags}&deviceType={deviceType}

Create or update the configuration for a specific device, device type and alarm type.

Input

The input parameters are provided as a JSON object in the payload (And you must specify the application/json content type in the request) except for id specified in the path and alarmFlags specified in the query string. All parameters are optional except for id.

Output

A simple message indicating that the configuration has been updated.

Permissions

Requires ADMIN permission on the location of the device being updated.

Delete Device Connfiguration

DELETE /api/v1/configuration/device/{id}?alarmFlags={alarmFlags}&deviceType={deviceType}

Delete a specific configuation setting.

Input

The input parameters are provided as either query strings or path parameters.

Output

A simple message indicating that the configuration has been deleted.

Permissions

Requires ADMIN permission on the location of the device being updated.

List Device Configurations

GET /api/v1/configuration/device/{id}

List configurations for a specific device.

Input

The only input parameter is specified in the path.

Output

A JSON array with the list of keys generated for the account. Each object has the following fields.

Permissions

Requires ACCESS permission on the location of the device being listed.

List Device Configuration Overrides

GET /api/v1/configuration/deviceoverride/{id}

List configuration overrides for a specific device.

Input

The only input parameter is specified in the path.

Output

A JSON array with the list of keys generated for the account. Each object has the following fields.

Permissions

Requires ACCESS permission on the location of the device being listed.

Device API

Register Device

PUT /api/v1/device/register/{id}

Register a device for use.

Input

The input parameters are provided as a JSON object in the payload (And you must specify the application/json content type in the request) except for the id of the device being registered.

Output

If successful a simple message saying if the device was created or updated.

Permissions

Requires ADMIN permission on both the new locationId of the device and the old one (If device is being updated).

Unregister Device

DELETE /api/v1/device/delete/{id}

Unregister a device from an account. Observe that this will not delete the data recorded by the device and if reregistered, it will stil be there.

Input

All input fields are specified in the path.

Output

If successful a simple message saying the device was deleted.

Permissions

Requires ADMIN permission on the locationId of the device.

Get Device

GET /api/v1/device/get/{id}

Get the dvice for a specific ID.

Input

All input fields are specified in the path.

Output

A JSON object with the device information.

Permissions

Requires ACCESS permission to the location the device belongs to.

List Devices

GET /api/v1/device/list/{id}

List the devices tied to a specific location id.

Input

All input fields are specified in the path.

Output

A JSON array with the list of devices being registered to the location. Each object has the following fields.

Permissions

Requires ACCESS permission to the location being listed.

List Active Alarms

GET /api/v1/device/alarms

List the devices that currentlly have active alarms.

Input

None.

Output

A JSON array with the list of active alarms.

Permissions

None required.

Get Device Data

GET /api/v1/device/data/{id}?offset={offset}&limit={limit}

Get the data collected for a specific device.

Input

All input fields are specified in the path or as query string parameters.

Output

A JSON array with the list of data points connected for the device. Each object has the following fields.

Permissions

Requires ACCESS permission to the location being listed.

Report Device Data

GET /api/v1/device/report/{id}?mc={mc}&battery={battery}&alarmFlags={alarmFlags}

This is the call that is used by devices to report back status to the service. The response returns configuration parameters for the device.

Input

All input parameters are query parameters except for the unique ID of the device.

Output

Output is a JSON object with the following fields.

The event values is an integer bit field with the following values.

Permissions

Requires no permissions or authentication. Additionally is the only call that can be called without HTTPS.