Connected Devices/Projects/Project Link/Taxonomy

Taxonomy Documentation

Github Link: http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/index.html

Current REST API

Account

• To create account:
  • POST http://localhost:3000/users/setup {"email": "a@b.com","username":"admin","password": "00000000"}
• To login:
  • POST http://localhost:3000/users/login (Header contains Authorization: Basic <base64 encode of username:password)

Service List

Services may requested by selector. A service selector is an object with the following fields:

• (optional) string `id`: accept only a service with a given id;
• (optional) string array of string `tags`: accept only services with all the tags in the array;
• (optional) object or array of objects `getters` (see GetterSelector): accept only services with channels matching all the selectors in this array;
• (optional) object or array of objects `setters` (see SetterSelector): accept only services with channels matching all the selectors in this array.

The GET accepts 0, 1 or an array of service selectors and will return all the services that match any of the selectors.

Example with 1 selector:

• Get services with tag "location: kitchen" and channel kind "OvenTemperature"
  • GET http://localhost:3000/api/v1/services { tags: "location: kitchen", setters: { kind: "OvenTemperature" } }

Example with 2 selectors:

• Get services with tag "location: kitchen" or "location: entrance":
  • GET http://localhost:3000/api/v1/services [{ tags: "location: kitchen" }, {tags: "location: entrance"}]

As a shortcut, providing no argument will locate all services:

• Get all services:
  • GET http://localhost:3000/api/v1/services

Channels

Channels are designed to be used by selector.

A selector is an object with the following fields:

• (optional) string id: accept only a channel with a given id;
• (optional) string `service`: accept only channels of a service with a given id;
• (optional) string|array of string `tags`: accept only channels with all the tags in the array;
• (optional) string|array of string `service_tags`: accept only channels of a service with all the tags in the array;
• (optional) string|object `kind` (see ChannelKind): accept only channels of a given kind.

While each field is optional, at least one field must be provided.

Generally, using an id is considered a bad idea, as this ties the application to a specific device, and this will fail if the device is replaced (consider that this is equivalent to using an IP address instead of a domain name).

Fetching

• Fetch values from all channels matching any of the selectors
  • PUT http://localhost:3000/api/v1/channels/get selector(s)

Example:

• • PUT http://localhost:3000/api/v1/channels/get [{"tags": "location: entrance", kind: "OpenClosed"}

Sending

• Send one values to all channels matching any of the selectors:
  • PUT http://localhost:3000/api/v1/channels/set {"select": selector(s), "value": value}

or

• Send a bunch of values to all channels matching any of the selectors:
  • PUT http://localhost:3000/api/v1/channels/set [{"select": selector(s), "value": value}, {"select": selector(s), "value: value}, ...]

See http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/values/enum.Value.html for the full documentation on values.

Specific services and channels

Time

• Get the current time
  • PUT http://localhost:3000/api/v1/channels/get {"id":"getter:timeofday.clock@link.mozilla.org"}

Camera

• Take a picture with camera
  • PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:snapshot.ae67e622-7a66-465e-bab0-28107b2df980@link.mozilla.org"}, "value": {"Unit": {}}}
• Get list of images taken
  • PUT http://localhost:3000/api/v1/channels/get {"id":"getter:image_list.ae67e622-7a66-465e-bab0-28107b2df980@link.mozilla.org"}
• Download the last taken picture
  • PUT http://localhost:3000/api/v1/channels/get {"id":"getter:image_newest.ae67e622-7a66-465e-bab0-28107b2df980@link.mozilla.org"}
• Get list of services that can take image (snapshot)
  • POST http://localhost:3000/api/v1/services {"setters":[{"kind":{"adapter":"Adapter","kind":"snapshot","type": "Json", "vendor":"DLink"} }]}

Tags

• Assign Tags to a service
  • POST http://localhost:3000/api/v1/services/tags {"services":[{"id":"thinkerbell-root-service"}],"tags":["Living Room"] }
  • Note: there can be multiple tags, (in array)
• Remove Tags of a service
  • DELETE http://localhost:3000/api/v1/services/tags {"services":[{"id":"thinkerbell-root-service"}],"tags":["Living Room"] }
  • Same URL, same body
• Query all devices matching the tag
  • POST http://localhost:3000/api/v1/services {"tags":["Living"]}

Recipe

• Send Recipe
• List available Recipes

WebPush

• Add push subscription
  • PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:subscribe.webpush@link.mozilla.org"}, "value": {"Json": {“subscriptions”:[{“push_uri”:”http://push.service/t54wtresfesfd”,”public_key”:”base64_encoded_key”}]}}}
• Remove push subscription
  • PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:unsubscribe.webpush@link.mozilla.org"}, "value": {"Json": {“subscriptions”:[{“push_uri”:”http://push.service/t54wtresfesfd”,”public_key”:”base64_encoded_key”}]}}}
• Set resources to receive notifications on
  • PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:resource.webpush@link.mozilla.org"}, "value": {"Json": {“resources”:[“res1”, “res2”]}}}
• Get current subscriptions
  • PUT http://localhost:3000/api/v1/channels/get {"select": {"id": "getter:subscription.webpush@link.mozilla.org"}, "value": {"Json": {}}}
• Get current resources receiving notifications on
  • PUT http://localhost:3000/api/v1/channels/get {"select": {"id": "getter:resource.webpush@link.mozilla.org"}, "value": {"Json": {}}}
• Trigger notification
  • PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:notify.webpush@link.mozilla.org"}, "value": {"Json": {“resource”:“res1”,”message”:”push_message_data”}}}