README.md in lelylan-rb-0.0.3 vs README.md in lelylan-rb-0.0.4

- old
+ new

@@ -51,12 +51,14 @@ ```ruby # Create a client oauth = OAuth2::Client.new(client_id, client_secret, site: site) # 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, scope: scope) +# => http://people.lelylan.com/oauth/authorize? +# redirect_uri=http://localhost:3000/callback& +#  scope=<scope>&response_type=code&client_id=<client-id> # 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) ``` @@ -67,12 +69,16 @@ ```ruby # Initialize Lelylan client lelylan = Lelylan::Client.new(token: token) -# Get the first device where the name matches with Dimmer +# Get the first device where the name matches with Dimmer. device = lelylan.devices(name: 'Dimmer').first + +# The client returns an Hashie (https://github.com/intridea/hashie) +puts device.uri # get the device uri +puts device.properties.first.value # get the first device property value ``` ### Realtime services When using the [subscription](http://dev.lelylan.com/api/realtime#language=node) services @@ -81,111 +87,92 @@ ```ruby lelylan = Lelylan::Client.new(client_id:'<client-id>', client_secret: '<client-secret>') subscriptions = lelylan.subscriptions ``` -## Authorization flows +### Implemented Services -Lelylan support three OAuth2 authorization flows. +**Devices** - 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). -### Authorization code flows - -```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) -``` - -### Implicit grant flow - -```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) -``` - -### Resource owner password credentials flow - -```ruby -oauth = OAuth2::Client.new(client_id, client_secret, site: site) -token = oauth.password.get_token('email', 'password') -``` - -Access tokens, when expired, are automatically refreshed. - - -## Lelylan Services - -### Devices - -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. +**Activations** - Easy way to move the device ownership between people. [See examples](http://dev.lelylan.com/api/devices#ruby). -### Histories - -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. +**Histories** - 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). -### Types - -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 +**Types** - 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). -### Properties - -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. +**Properties** - 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). -### Functions - -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. +**Functions** - 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). -### Statuses - -Properties are not always enough to describe the status of a device. Think at a roller +**Statuses** - 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). -### Locations - -Locations are the places we live in and where physical devices are placed. Lelylan identifies +**Locations** - 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 - -Physical devices are the real objects you physically interact with everyday of your life +**Physical Devices** - 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). -### Subscriptions - -Get real-time updates by subscribing to a resource and its related event. +**Subscriptions** - Get realtime updates by subscribing to a resource and its related event. [See examples](http://dev.lelylan.com/api/realtime#ruby). -### Authenticated User Profile - -Returns extended information for the authenticated user. +**User Profile** - Returns extended information for the authenticated user. [See examples](http://dev.lelylan.com/api/core#get-a-user-ruby). -## Errors +### Authorization flows +#### Authorization code flows + +```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) +``` + +#### Implicit grant flow + +```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) +``` + +#### Resource owner password credentials flow + +```ruby +oauth = OAuth2::Client.new(client_id, client_secret, site: site) +token = oauth.password.get_token('email', 'password') +``` + +Access tokens, when expired, are automatically refreshed. + + +### Errors + Exceptions are raised when a 4xx or 5xx status code is returned. Lelylan::BadRequest # 400 Lelylan::Unauthorized # 401 Lelylan::NotFound # 404 @@ -197,22 +184,25 @@ Through the error message attribute you can access the error information. ```ruby begin - @type = Lelylan::Type.type("https://type.lelylan.com/types/wrong") + device = lelylan.device('<id>') rescue Lelylan::Error => e - puts "The resource #{e.message.error.uri} was not found" + puts e.message end ``` +Unluckily the `#message` method can only be a string. For this reason we +can't return a JSON structure when lelylan offers it, but we return the +`error.description` value. Learn more about the [error response structure](http://dev.lelylan.com/api/core#errors). -## Configurations +### Configurations -### API endpoint +#### API endpoint Configuration block. ```ruby Lelylan.configure { |c| c.endpoint = 'https://localhost:8000' } @@ -240,27 +230,37 @@ * Fork and clone the repository. * Run `gem install bundler` to get the latest for the gemset. * Run `bundle install` for dependencies. * Run `bundle exec guard` and press enter to execute all specs. +### Running locally -## Spec guidelines +Whenever you want to use the source code from your IRB session simply import `lib/`. +``` +$ git clone https://github.com/lelylan/lelylan-rb +$ cd lelylan-rb +$ irb -I lib/ +$ > require 'lelylan' +``` + +### Spec guidelines + Follow [rspec best practices](http://betterspecs.org) guidelines. -## Coding guidelines +### Coding guidelines Follow [github](https://github.com/styleguide/) guidelines. -## Feedback +### Feedback 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)