Losant Ruby REST API Client

Build Status Gem Version

The Losant REST API client provides a simple way to use the comprehensive Losant API. You can authenticate either as a Losant device or with your user account, and have access to all the functionality of the Losant platform.

This client works with Ruby 2.1 and higher. It uses HTTParty under the covers for the actual HTTP communication.


Installation

The latest stable version is available in RubyGems and can be installed using

gem install losant_rest


Example

Below is a high-level example of using the Losant Ruby REST API client to authenticate against the Losant Platform and report state for a device.

require "losant_rest"

response = LosantRest.auth.authenticate_device(credentials: {
  deviceId: "my-device-id",
  key: "my-app-access-key",
  secret: "my-app-access-secret"
})

LosantRest.auth_token = response["token"]
app_id = response["applicationId"]

state = { data: { temperature: AnalogSensor.read } }
response = LosantRest.device.send_state(deviceId: "my-device-id",
  applicationId: app_id, deviceState: state)

puts response
# { "success" => true }


API Documentation

LosantRest

LosantRest is the wrapping module, but it also acts as a singleton Client instance. So if you only need a single client instance, you do not need to instantiate one yourself - the LosantRest module will act exactly like an instance of LosantRest::Client.


LosantRest::Client

A client is a single api instance. By default, it is unauthenticated, but can be given an access token to perform authenticated requests.

Initializer

LosantRest::Client.new(auth_token: nil, url: "https://api.losant.com")

The Client() initializer takes the following arguments:

  • auth_token
    The access token to be used for authentication - by default there is no access token. An access token can be acquired through either of the Auth methods.

  • url
    The url of the Losant API - by default https://api.losant.com.

Accessors

  • auth_token
    The auth token can be accessed or changed after Client creation through this accessor.

  • url
    The api base url can be accessed or changed after Client creation through this accessor.

Resources

Each of the following is a method on the client object, and returns a wrapper for the actions against that particular resource. See each resource documentation file for more information.

  • application_key
    Contains all the actions that can be performed against a single Application Key - for instance, getting info on a single key or revoking a key.

  • application_keys
    Contains all of the actions that can be performed against the collection of Application Keys belonging to an Application - such as listing all keys or creating a new key.

  • application
    Contains all of the actions that can be performed against a single Application, which include things like getting info on an application or modifying an application.

  • applications
    Contains all of the actions that can be performed against the set of Applications that the currently authenticated user has access to - such as listing the applications or creating a new application.

  • auth
    Contains the actions used for authenticating against the api, either as a user or as a device. The result of authentication calls contain the auth_token needed for authenticated calls - see the examples for more details.

  • dashboard
    Contains all of the actions that can be performed against a single Dashboard, which include things like getting info on a dashboard or modifying a dashboard.

  • dashboards
    Contains all of the actions that can be performed against the set of Dashboards that the currently authenticated user has access to - such as listing the dashboards or creating a new dashboard.

  • data
    Contains the actions for querying against historical Device data across an Application.

  • device
    Contains all the actions that can be performed against a single Device - for instance, getting info on a single device or reporting the current state of a device.

  • devices
    Contains all of the actions that can be performed against the collection of Devices belonging to an Application - such as listing all devices or sending a command to a set of devices.

  • device_recipe
    Contains all the actions that can be performed against a single Device Recipe, which include things like removing a device recipe or creating a device from a device recipe.

  • device_recipes
    Contains all the actions that can be performed against the collection of Device Recipes belonging to an Application - such as listing recipes or creating a new recipe.

  • event
    Contains all the actions that can be performed against a single Event, such as commenting on or changing the state of an event.

  • events
    Contains all the actions that can be performed against the collection of Events belonging to an Application - such as listing open events or creating a new event.

  • flow
    Contains all the actions that can be performed against a single Workflow, such as enabling or disabling a workflow, or triggering a virtual button in the workflow.

  • flows
    Contains all the actions that can be performed against the collection of Workflows belonging to an Application - such as listing the workflows or creating a new workflow.

  • me
    Contains the actions for operating against the currently authenticated User such as changing the password or linking against external services.

  • org
    Contains all the actions that can be performed against a single Organization, things like inviting a user to the organization, or modifying the organization.

  • orgs
    Contains all of the actions that can be performed against the set of Organizations that the currently authenticated user has access to - such as listing the organizations or creating a new organization.

  • webhook
    Contains all the actions that can be performed against a single Webhook, for instance modifying the verification settings or removing the webhook.

  • webhooks
    Contains all the actions that can be performed against the collection of Webhooks belonging to an Application - such as listing the webhooks or creating a new webhook.


LosantRest::ResponseError

When the Losant API returns a unsuccessful response, an instance of ResponseError is thrown.

Accessors

  • code
    The status code returned from the Losant API.

  • type
    The type of error that occured, such as "Validation" or "Authorization".

  • message
    A more detailed message about the particulars of the error.


Copyright (c) 2016 Losant IoT, Inc

https://www.losant.com