README.md in lelylan-rb-0.0.1 vs README.md in lelylan-rb-0.0.2

- old
+ new

@@ -1,144 +1,190 @@ # Lelylan Ruby Gem Ruby client library for [Lelylan API](http://dev.lelylan.com) +## What is Lelylan +Lelylan makes it easy for developers to monitor and control all devices in +your house providing a simple, self descriptive and consistent representation of them. Lelylan +maps every device in your house to a unique URI which will provide a simple access over it. + +With Lelylan developers can build secure applications and services that use real-time data +coming from the real world to create the future connected house. + ## Requirements Ruby client library is tested against MRI 1.9.3. ## Installation -Install gem using Bundler. +Install the client using Bundler. - gem 'lelylan-rb', require: 'lelylan' +```ruby +gem 'lelylan-rb', require: 'lelylan' +gem 'oauth2' +``` Development version. - gem 'lelylan-rb', require: 'lelylan', git: 'https://github.com/lelylan/lelylan-rb', branch: 'dev' +```ruby +gem 'lelylan-rb', require: 'lelylan', git: 'https://github.com/lelylan/lelylan-rb', branch: 'master' +``` - -## Resources - -* [Ruby gem documentation](http://rdoc.info/gems/lelylan-rb) -* [Lelylan API](http://dev.lelylan.com) - - ## Getting started -Require gems. +### Require Gem - require 'rubygems' - require 'lelylan-rb' +```ruby +require 'rubygems' +require 'lelylan-rb' +require 'oauth2' +``` +### Get an access token -### Create the access token +First of all you need an access token to authoraze your requests in +Lelylan. To get one use the [OAuth2 gem](https://github.com/intridea/oauth2/) +and if you are not used to OAuth2 concepts, take 10 minutes and read the +related documentation in the [dev center](http://dev.lelylan.com/api/oauth#language=node). -Create a client (uses the [OAuth2 gem](https://github.com/intridea/oauth2/)). - oauth = OAuth2::Client.new(client_id, client_secret, site: site) +```ruby +# Create a client +oauth = OAuth2::Client.new(client_id, client_secret, site: site) -Redirect the application to the Lelylan authorization page. +# Redirect the application to the Lelylan authorization page +redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri) +# => http://people.lelylan.com/oauth/authorize?redirect_uri=http://localhost:3000/callback&scope=devices&response_type=code&client_id=<client-id> - redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri) +# Get the access token object (authorization code is given from the previous step) +token = oauth.auth_code.get_token(params[:code], redirect_uri: redirect_uri) +``` -Create the access token. The params[:code] contains the authorization -code created from Lelylan and sent to the redirect_uri. +### Lelylan access - token = oauth.auth_code.get_token(params[:code], redirect_uri: redirect_uri) +Once you have the access token you can access to the Lelylan API. The +following example shows how to print in the console a list of owned devices. -### Create the Lelylan client. +```ruby +# Initialize Lelylan client +lelylan = Lelylan::Client.new(token: token) - client = Lelylan::Client.new(token: token) +# Get the first device where the name matches with Dimmer +device = lelylan.devices(name: 'Dimmer').first +``` -### Access Lelylan API +### Realtime services -Get 10 devices. +When using the [subscription](http://dev.lelylan.com/api/realtime#language=node) services +you don't need an access token. In this case what you need is to set the client credentials. - client.devices(per: 10) +```ruby +lelylan = Lelylan::Client.new(client_id:'<client-id>', client_secret: '<client-secret>') +subscriptions = lelylan.subscriptions +``` -Get a device based on its URI. +## Authorization flows - client.device('http://api.lelylan.com/devices/:id') +Lelylan support three OAuth2 authorization flows. -Search a device based on its name. +### Authorization code flows - client.devices(name: 'Dimmer').first +```ruby +oauth = OAuth2::Client.new(client_id, client_secret, site: site) +redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri) +token = oauth.auth_code.get_token(params[:code], redirect_uri: redirect_uri) +``` -Create a device (in this case we suppose the type is a dimmer) +### Implicit grant flow - device = client.create_device(name: 'Closet dimmer', type_uri: dimmer.uri) +```ruby +oauth = OAuth2::Client.new(client_id, client_secret, site: site) +redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri) +token = OAuth2::AccessToken.from_kvform(client, params) +``` -Execute a function. +### Resource owner password credentials flow - client.execute(device.uri, function.uri) +```ruby +oauth = OAuth2::Client.new(client_id, client_secret, site: site) +token = oauth.password.get_token('email', 'password') +``` -Get a public type based on its URI. Remember, when a resource is public the client -with a token is not needed. +Access tokens, when expired, are automatically refreshed. - Lelylan.type('http://api.lelylan.com/types/:id') +## Lelylan Services -## More examples +### Devices -For more examples check out the [ruby gem documentation](http://rdoc.info/gems/lelylan-rb). +The Device API defines a set of services to monitor and control every existing device. +Its final goal is to map every device to a unique URI which provides control over it. +[See examples](http://dev.lelylan.com/api/devices#ruby). -* [Device examples](docs/Lelylan/Client/Devices) -* [Consumption examples](docs/Lelylan/Client/Consumptions) -* [Hisotry examples](docs/Lelylan/Client/Histories) -* [Types examples](docs/Lelylan/Client/Types) -* [Properties examples](docs/Lelylan/Client/Properties) -* [Functions examples](docs/Lelylan/Client/Functions) -* [Statuses examples](docs/Lelylan/Client/Statuses) -* [Categories examples](docs/Lelylan/Client/Categories) -* [Locations examples](docs/Lelylan/Client/Locations) +### Histories -## Authorization flows +When a device updates its properties or executes a function a new history resource with +a snapshot of all device properties is created by Lelylan, also the ones that has not been +updated. This makes it easy to recreate previous device status and extract usage patterns +to improve the way people live their house. +[See examples](http://dev.lelylan.com/api/devices/histories#ruby). -Lelylan support four OAuth2 authorization flows. +### Types -### Authorization code flows +A type describes the structure of a device. In its simplest form every type can be defined +as the combination of three key elements: properties (what vary during time), functions +(what a device can do), statuses (what a device is in a specific time of its life). +[See examples](http://dev.lelylan.com/api/types#ruby). - oauth = OAuth2::Client.new(client_id, client_secret, site: site) - redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri) - token = oauth.auth_code.get_token(params[:code], redirect_uri: redirect_uri) +### Properties -### Implicit grant flow +A property is whatever vary in a device during time. It can be the intensity in a dimmer, +the temperature in a cooling system or the volume in a television. +[See examples](http://dev.lelylan.com/api/types/properties#ruby). - oauth = OAuth2::Client.new(client_id, client_secret, site: site) - redirect oauth.auth_code.authorize_url(redirect_uri: redirect_uri) - token = OAuth2::AccessToken.from_kvform(client, params) +### Functions -### Resource owner password credentials flow +Functions defines the daily interactions you have with the devices in your house, for +example when you turn on a light, close a door or raise the temperature in a room. +With functions you can control any device in the same way you do everyday of your life. +[See examples](http://dev.lelylan.com/api/types/functions#ruby). - oauth = OAuth2::Client.new(client_id, client_secret, site: site) - token = oauth.password.get_token('email', 'password') +### Statuses -### Client credentials flow +Properties are not always enough to describe the status of a device. Think at a roller +shutter for example. It has the property aperture that is 100 when open or 0 when closed. +But what if the roller shutter is opening? It is nether open or close. To have a complete +control over the device status in a specific moment of its life is to use the status API. +[See examples](http://dev.lelylan.com/api/types/statuses#ruby). - token = oauth.client_credentials.get_token +### Locations -All access tokens, when expired, are automatically refreshed. +Locations are the places we live in and where physical devices are placed. Lelylan identifies +three types of locations usually organized in a hierarchical structure: houses, floors and +rooms. +[See examples](http://dev.lelylan.com/api/locations#ruby). +### Physical devices -## Settings +Physical devices are the real objects you physically interact with everyday of your life +like lights, appliances, alarms and more. To enable the communication between Lelylan and +physical devices they should provide a simple set of web services. +[See examples](http://dev.lelylan.com/api/physicals#ruby). -### API endpoint +### Subscriptions -Configuration block. +Get real-time updates by subscribing to a resource and its related event. +[See examples](http://dev.lelylan.com/api/realtime#ruby). - Lelylan.configure { |c| c.endpoint = 'https://lelylan.yourhouse.com' } - @client = Lelylan::Client.new(token: token) +### Authenticated User Profile -Client instance. +Returns extended information for the authenticated user. +[See examples](http://dev.lelylan.com/api/core#get-a-user-ruby). - @client = Lelylan::Client.new(token: token) - @client.endpoint = 'https://lelylan.yourhouse.com' - ## Errors Exceptions are raised when a 4xx or 5xx status code is returned. Lelylan::BadRequest # 400 @@ -150,22 +196,45 @@ Lelylan::ServiceUnavailable # 503 Through the error message attribute you can access the error information. - begin - @type = Lelylan::Type.type("https://type.lelylan.com/types/not_existing_uri") - rescue Lelylan::NotFound => e - puts "The resource #{e.message.error.uri} was not found" - end +```ruby +begin + @type = Lelylan::Type.type("https://type.lelylan.com/types/wrong") +rescue Lelylan::NotFound => e + puts "The resource #{e.message.error.uri} was not found" +end +``` -Learn more about the [error response structure](http://dev.lelylan.com/rest/core/#errors). +Learn more about the [error response structure](http://dev.lelylan.com/api/core#errors). +## Configurations + +### API endpoint + +Configuration block. + +```ruby +Lelylan.configure { |c| c.endpoint = 'https://localhost:8000' } +lelylan = Lelylan::Client.new(token: token) +``` + +Client instance. + +```ruby +lelylan = Lelylan::Client.new(token: token) +lelylan.endpoint = 'https://lelylan.yourhouse.com' +``` + +Learn more about the [error response structure](http://dev.lelylan.com/api/core#errors). + + ## Contributing -Fork the repo on github and send a pull requests with topic branches. Do not forget to +Fork the repo on github and send a pull requests with topic branches. Do not forget to provide specs to your contribution. ### Running specs @@ -175,11 +244,11 @@ * Run `bundle exec guard` and press enter to execute all specs. ## Spec guidelines -Follow [rspec best practices](https://docs.google.com/document/d/1gi00-wwPaLk5VvoAJhBVNh9Htw4Rwmj-Ut88T4M2MwI/edit?hl=en#) guidelines. +Follow [rspec best practices](http://betterspecs.org) guidelines. ## Coding guidelines Follow [github](https://github.com/styleguide/) guidelines. @@ -189,13 +258,14 @@ Use the [issue tracker](http://github.com/lelylan/lelylan-rb/issues) for bugs. [Mail](mailto:touch@lelylan.com) or [Tweet](http://twitter.com/lelylan) us for any idea that can improve the project. -## Links +## Links * [GIT Repository](http://github.com/lelylan/lelylan-rb) +* [Lelylan Ruby Website](http://lelylan.github.com/lelylan-rb). * [Lelylan Dev Center](http://dev.lelylan.com) * [Lelylan Site](http://lelylan.com) ## Authors @@ -208,11 +278,12 @@ Special thanks to the following people for submitting patches. ## Changelog -See [CHANGELOG](people/blob/master/CHANGELOG.md) +See [CHANGELOG](https://github.com/lelylan/lelylan-rb/blob/master/CHANGELOG.md) ## Copyright -Copyright (c) 2013 [Lelylan](http://lelylan.com). See [LICENSE](people/blob/master/LICENSE.md) for details. +Copyright (c) 2013 [Lelylan](http://lelylan.com). +See [LICENSE](https://github.com/lelylan/lelylan-rb/blob/master/LICENSE.md) for details.