rhoconnect 3.0.0.beta1

data/doc/rest-api.txt

@@ -0,0 +1,367 @@
+RhoConnect REST API
+===
+The RhoConnect REST API allows you to control, monitor, and debug a running RhoConnect application using a simple HTTP API.
+
+Below we describe the REST API using ruby sample code.
+
+## API Errors
+All API calls will return http 200 and requested data (if applied). Otherwise, API will return http error code and specific error message in the http message body.
+
+	:::ruby
+	def handle_api_error(error_message)
+	  @errors ||= []
+	  begin
+	    yield
+	  rescue RestClient::Exception => re
+	    if re.response.body.nil? or re.response.body.length == 0
+	      @errors << "#{error_message}: [#{re.http_code}] #{re.message}"  
+	    else
+	      @errors << "#{error_message}: #{re.response.body}"
+	    end
+	  rescue Exception => e      
+	    @errors << "#{error_message}: #{e.message}"
+	  end     
+	end  
+
+	handle_api_error("Can't get license information") do
+	  @license_info = JSON.parse(
+		RestClient.post(
+		  "#{server}/api/get_license_info", 
+	      { :api_token => @token }.to_json, 
+	      :content_type => :json
+	    ).body
+	  )
+	end
+
+## API Methods
+
+### `get_api_token`
+Before you can use RhoConnect API you should get API token:
+
+	:::ruby
+	require 'rest_client'
+	require 'json'
+
+	server = "http://localhost:9292"
+	login = "rhoadmin"
+	password = ""
+
+	res = RestClient.post("#{server}/login", { :login => login, :password => password }.to_json, :content_type => :json)
+	rhoconnect_session_cookie = 'rhoconnect_session='  + res.cookies['rhoconnect_session']
+	token = RestClient.post("#{server}/api/get_api_token",'',{ 'Cookie' => rhoconnect_session_cookie })
+      	
+### `get_license_info`
+Returns license information of the currently used license
+
+	:::ruby
+	license_info = RestClient.post(
+	  "#{server}/api/get_license_info",
+      {:api_token => token}.to_json, :content_type => :json
+    ).body
+
+### `reset`
+Reset the server: flush db and re-bootstrap server
+
+	:::ruby
+	RestClient.post("#{server}/api/reset",
+  	  { :api_token => token }.to_json, 
+      :content_type => :json
+    )
+
+### `ping`
+Sends PUSH message to all devices of the specified user:
+
+	:::ruby
+	# :message - message which will be used to display notification popup dialog on the device
+	# :badge - iphone specific badge
+	# :sound - name of the sound file to play upon receiving PUSH notification
+	# :vibrate - number of seconds to vibrate upon receiving PUSH notification
+	# :sources - list of data source names to be synced upon receiving PUSH notification
+	ping_params = {
+      :api_token => token,
+      :user_id => user_id,
+      :sources => source_name,
+      :message => 'hello world',
+      :vibrate => 2000,
+      :sound => 'hello.mp3'
+    }
+
+	RestClient.post(
+	  "#{server}/api/ping",ping_params.to_json, 
+	  :content_type => :json
+	) 
+
+### `push_objects`
+Push new objects or object updates to RhoConnect. These changes will be sent to device next time it synchronizes.
+
+**NOTE: you may use [ping](/rhoconnect/push) to notify client and trigger sync.**
+
+	:::ruby
+	# list of objects in the canonical hash of hashes structure
+	data = {
+	  '5' => {
+	    'name' => 'iPhone'  
+	  }
+	}
+	RestClient.post(
+	  "#{server}/api/push_objects", 
+	  { 
+		:api_token => token, 
+        :user_id => user_id, 
+	    :source_id => source_name, 
+	    :objects => data 
+	  }.to_json, 
+	  :content_type => :json
+	)
+
+### `push_deletes`
+Delete objects from RhoConnect. These objects will be deleted from the device the next time it synchronizes.
+
+**NOTE: You may use [ping](/rhoconnect/push) to notify client and trigger sync.**
+
+	:::ruby
+	# object_ids is an array of objects to be deleted
+	RestClient.post(
+	  "/api/push_deletes", 
+	  { 
+		:api_token => api_token, 
+	    :user_id => user_id, 
+	    :source_id => source_name, 
+	    :objects => object_ids 
+      }.to_json, 
+     :content_type => :json
+    )
+
+### `list_users`
+List users registered with this RhoConnect application.
+
+	:::ruby
+ 	users = RestClient.post(
+	  "#{server}/api/list_users",
+      { :api_token => token }.to_json, 
+      :content_type => :json
+    ).body
+
+### `create_user`
+Create a user in this RhoConnect application.
+
+	:::ruby
+	RestClient.post("#{server}/api/create_user",
+	  { 
+		:api_token => token,
+	    :attributes => { 
+		  :login => login, 
+		  :password => password 
+		} 
+	  }.to_json, 
+	  :content_type => :json
+	)
+
+### `delete_user`
+Delete User and all associated devices from the RhoConnect application.
+
+	:::ruby
+	RestClient.post(
+	  "#{server}/api/delete_user",
+	  { 
+		:api_token => token, 
+		:user_id => user_id 
+	  }.to_json, 
+	 :content_type => :json
+	)
+
+### `list_clients`
+List clients (devices) associated with given user.
+
+	:::ruby
+	clients = RestClient.post("#{server}/api/list_clients", 
+	  { 
+		:api_token => token, 
+		:user_id => user_id 
+	  }.to_json, 
+	 :content_type => :json
+	).body
+
+Returns list of client ids.
+
+### `create_client`
+Creates a client (device) for a given user.
+ 
+	:::ruby
+	RestClient.post(
+	  "#{server}/api/create_client",
+	  { 
+		:api_token => token, 
+		:user_id => user_id 
+	  }.to_json, 
+	  :content_type => :json
+	).body
+
+### `delete_client`
+Deletes the specified client (device).
+
+	:::ruby
+	RestClient.post(
+	  "#{server}/api/delete_client",
+	  { 
+		:api_token => token, 
+		:user_id => user_id,  
+		:client_id => client_id 
+	  }.to_json, 
+	 :content_type => :json
+    )    
+
+### `get_client_params`
+Returns client (device) attributes, such as `device_type`, `device_pin`, `device_port`. These attributes used by [RhoConnect push](/rhoconnect/push). 
+
+	:::ruby
+	RestClient.post(
+	  "#{server}/api/get_client_params", 
+	  { 
+		:api_token => token, 
+		:client_id => client_id 
+	  }.to_json, 
+	  :content_type => :json
+	).body
+
+### `list_client_docs`
+Returns list of document keys associated with particular client. These documents are used by the server to sync data with the client. 
+CD (:cd) - client document; represents the state of the client (set of all objects on the given client).
+
+	:::ruby
+	RestClient.post(
+	  "#{server}/api/list_client_docs", 
+	  { 
+		:api_token => token, 
+		:source_id => source_id, 
+		:client_id => client_id 
+	  }.to_json, 
+	  :content_type => :json
+	).body
+
+### `list_sources`
+Return list of source adapters for this RhoConnect application.
+
+	:::ruby
+	sources = RestClient.post("#{server}/api/list_sources", 
+	  { 
+		:api_token => token, 
+		:partition_type => partition 
+	  }.to_json, 
+	  :content_type => :json
+	).body
+
+### `get_source_params`
+Return attributes associated with a given source:
+
+* `name` - name of the data source
+* `poll_interval` - query poll interval; defines how often RhoConnect will call source adapter to query for new data, set to -1 to disable polling, 0 to always poll
+* `partition_type` - to share data across all users, set partition to :app; otherwise use `:user` partition (default)  
+* `sync_type` - set to `:bulk_only` to disable `:incremental` sync; regular sync is `:incremental` (default) 
+* `queue` - name of the queue for both query and create/update/delete (CUD) jobs (used if no specific queues not specified)
+* `query_queue` - name of query queue
+* `cud_queue` - name of CUD queue
+
+**NOTE: query or create/update/delete methods of the source adapter will be executed [asynchronously](/rhoconnect/async-jobs) if a queue name is defined.**
+
+	:::ruby
+	attributes = RestClient.post("#{server}/api/get_source_params", 
+	  { 
+		:api_token => token, 
+		:source_id => source_id 
+	  }.to_json, 
+	  :content_type => :json
+	).body
+
+### `set_refresh_time`
+Sets source poll interval to "current time plus x seconds".
+
+	:::ruby
+	RestClient.post(
+	  "/api/set_refresh_time", 
+	  { 
+		:api_token => @api_token, 
+	    :source_name => source_name, 
+	    :user_name => user, 
+	    :refresh_time => 100 
+	  }.to_json, 
+	  :content_type => :json
+	)
+
+This will set the refresh time to 100 seconds from the current time.  Calling `set_refresh_time` with no `:refresh_time` will trigger a refresh on the sync request for the source.
+
+### `list_source_docs`
+Return list of document keys associated with given source and user. 
+
+If `:user_id` set to '*', this call will return list of keys for 'shared' documents. 
+
+MD(:md) - master document; represents state of the backend (set of all objects for the given app/user/source on the backend service).
+
+	:::ruby
+	docs = RestClient.post(
+	  "#{server}/api/list_source_docs", 
+	  { 
+		:api_token => token, 
+		:source_id => source_id, 
+		:user_id => user_id 
+	  }.to_json, 
+	  :content_type => :json
+	).body
+
+### `get_db_doc`
+Return content of a given document (client or source).
+
+	:::ruby
+	res = RestClient.post(
+	  "#{server}/api/get_db_doc", 
+	  { 
+		:api_token => token, 
+		:doc => doc, 
+		:data_type => data_type 
+	  }.to_json, 
+	  :content_type => :json
+	).body
+
+`:data_type` should be 'string' for the documents containing single string (size or token docs); otherwise this call will return hash of hashes.
+
+### `set_db_doc`
+Sets the content of the specified server document. Data should be either a string or hash of hashes. Data type should be set accordingly.
+
+	:::ruby
+	RestClient.post(
+	  "#{server}/api/set_db_doc", 
+	  { 
+		:api_token => token, 
+		:doc => doc, 
+		:data => data, 
+		:data_type => data_type 
+	  }.to_json, 
+	  :content_type => :json
+    )
+
+### `stats`
+Retrieves stats for a given metric key:
+
+	:::ruby
+	RestClient.post(
+	  "#{server}/api/stats", 
+	  { 
+		:api_token => @api_token, 
+		:metric => 'foo', 
+		:start => 0, 
+		:finish => -1 
+	  }.to_json, 
+	  :content_type => :json
+	)
+
+Retrieves a list of metric keys matching a given pattern.  This supports 'glob' or '*' style pattern matching.  For example, all metric keys associated with 'Product' source adapter methods:
+
+	:::ruby
+	RestClient.post(
+	  "#{server}/api/stats", 
+	  { 
+		:api_token => @api_token, 
+		:names => 'sources:*:Product' 
+	  }.to_json, 
+	  :content_type => :json
+	)

data/doc/source-adapters.txt

@@ -0,0 +1,325 @@
+RhoConnect Source Adapters
+===
+
+Connecting to a backend service with RhoConnect requires that you write a small amount of Ruby code for the query, create, update and delete operations of your particular enterprise backend. The collection of the Ruby code for these operations we refer to as a "source" or "source adapter".
+
+## Generate Source Adapter
+
+Adding a new source adapter to your RhoConnect application is simple:
+  	
+	:::term
+	$ cd storeserver
+  	$ rhoconnect source product
+
+This will generate a new ruby class called `sources/product.rb`:
+
+	:::ruby
+	class Product < SourceAdapter
+	  def initialize(source)
+	    super(source)
+	  end
+ 
+	  def login
+	    # TODO: Login to your data source here if necessary
+	  end
+ 
+	  def query
+	    # TODO: Query your backend data source and assign the records 
+	    # to a nested hash structure called @result. For example:
+	    # @result = { 
+	    #   "1"=>{"name"=>"Acme", "industry"=>"Electronics"},
+	    #   "2"=>{"name"=>"Best", "industry"=>"Software"}
+	    # }
+	    raise SourceAdapterException.new("Please provide some code to read records from the backend data source")
+	  end
+ 
+	  def sync
+	    super
+	  end
+ 
+	  def create(create_hash)
+	    # TODO: Create a new record in your backend data source
+	    # If your rhodes rhom object contains image/binary data 
+	    # (has the image_uri attribute), then a blob will be provided
+	    raise "Please provide some code to create a single record in the backend data source using the create_hash"
+	  end
+ 
+	  def update(update_hash)
+	    # TODO: Update an existing record in your backend data source
+	    raise "Please provide some code to update a single record in the backend data source using the update_hash"
+	  end
+ 
+	  def delete(delete_hash)
+	    # TODO: write some code here if applicable
+	    # be sure to have a hash key and value for "object"
+	    # for now, we'll say that its OK to not have a delete operation
+	    # raise "Please provide some code to delete a single object in the backend application using the object_id"
+	  end
+ 
+	  def logoff
+	    # TODO: Logout from the data source if necessary
+	  end
+	end
+
+It also adds a spec file `spec/sources/product_spec.rb` and updates `settings/settings.yml` with the product adapter to the sources section with some default options:
+
+ 	:::yaml
+	:sources: 
+  	  Product: 
+    	:poll_interval: 300
+
+## Source Adapter API
+The source adapter interface is described below, your source adapter can use any of these methods to interact with your backend service.
+
+### `login`
+Login to your backend service (optional).
+
+	:::ruby
+	def login
+	  MyWebService.login(current_user.login)
+	end
+
+### `logoff`
+Logoff from your backend service (optional).
+
+	:::ruby
+	def logoff
+	  MyWebService.logoff(current_user.login)
+	end
+
+### `query(params = nil)`
+Query your backend service and build a hash of hashes (required).
+
+**NOTE: This method must assign `@result` to a hash of hashes.  If @result is `nil` or `{}`, the master document will be erased from redis.**
+
+	:::ruby
+	def query
+	  parsed = JSON.parse(RestClient.get("#{@base}.json").body)
+
+      @result = {}
+	  parsed.each do |item|
+	    @result[item["product"]["id"].to_s] = item["product"]
+	  end if parsed
+	end
+
+### `search(params)`
+Search your backend based on params and build a hash of hashes (optional).  Similar to query, however the master document accumulates the data in `@result` instead of replacing when it runs.
+
+	:::ruby
+	def search(params)
+	  parsed = JSON.parse(RestClient.get("#{@base}.json").body)
+
+      @result = {}
+	  parsed.each do |item|
+		if item["product"]["name"].downcase == params['name'].downcase
+	      @result[item["product"]["id"].to_s] = item["product"]
+	    end
+	  end if parsed
+	end
+
+Next, you will need to add search to your Rhodes application. For details, see the [Rhodes search section](/rhodes/synchronization#filtering-datasets-with-search).
+	
+### `create(create_hash)`
+Create a new record in the backend (optional).
+
+**NOTE: RhoConnect can establish a 'link' between the local record id provided by the client and the new record id provided by the backend service.  To enable this link, return the new record id as a string.**
+
+	:::ruby
+	def create(create_hash)
+	  res = MyWebService.create(create_hash)
+
+	  # return new product id so we establish a client link
+	  res.new_id
+	end
+
+### `update(update_hash)`
+Update an existing record in the backend (optional).
+
+	:::ruby
+	def update(update_hash)
+	end
+
+### `delete(delete_hash)`
+Delete an existing record in the backend (optional).
+
+	:::ruby
+	def delete(delete_hash)
+	  MyWebService.delete(delete_hash['id'])
+	end
+	
+### `current_user`
+Returns the current user which called the adapter.  For example, you could filter results for a specific user in  your query method:
+
+	:::ruby
+	def query
+	  @result = MyWebService.get_records_for_user(current_user.login)
+	end
+	
+### `stash_result`
+Saves the current state of `@result` to redis and assigns it to `nil`.  Typically this is used when your adapter has to paginate through backend service data.
+
+ 	:::ruby
+	def query
+	  @result = {}
+	  ('a'..'z').each_with_index do |letter,i|
+		@result ||= {}
+	    @result.merge!( DictionaryService.get_records_for(letter) )
+		stash_result if i % 2
+	  end
+	end
+
+## Data Partitioning
+Data is stored in RhoConnect using [redis sets](http://redis.io/commands#set).  The `@result` hash from the `query` method is stored in redis and referred to as the Master Document or MD.  
+
+The MD is referenced in RhoConnect by a corresponding partition.  Source adapters can partition data in two ways: user and app.  As you might have guessed, user partitioning stores a copy of the source adapter MD for each user (one copy shared across all devices for a user).  
+
+Likewise, app partitioning stores one copy of the source adapter MD for the entire application (all users and devices share the same data).  App partitioning can be particularly useful if you have source adapters which retrieve large amounts of data that is fixed from user to user, for example a global product catalog.  Using app partitioning wherever possible ***greatly reduces*** the amount of data in redis.
+
+### User Partition
+User partitioning is the default scheme for source adapters, however you can explicitly define it in `settings/settings.yml` with:
+
+	:::yaml
+	:sources: 
+  	  Product: 
+    	:poll_interval: 300
+    	:partition_type: user
+
+### App Partition
+Enable app partitioning the same way:
+	
+	:::yaml
+	:sources: 
+  	  Product: 
+    	:poll_interval: 300
+    	:partition_type: app
+
+Now you have a single copy of the `Product` source adapter dataset for all users.
+
+## Pass Through
+RhoConnect provides a simple way to keep data out of redis.  If you have sensitive data that you do not want saved in redis, add the pass_through option in settings/settings.yml for each source:
+ 
+	:::yaml
+	:sources: 
+  	  Product: 
+    	:pass_through: true
+
+**NOTE: When running query or search the entire data set will be returned from your backend service. **
+
+## Store API
+RhoConnect provides a simple redis interface for saving/retrieving arbitrary data.  This is useful if you want to save data in your application to be used later (i.e. in an async job or a subsequent source adapter execution).
+
+	:::ruby
+	Store.put_value('hello','world')
+
+	Store.get_value('hello') #=> 'world'
+
+	# You can store nested hashes too!
+	Store.put_data(
+	  'mydata',
+	  {
+	    '1' => { 'hello' => 'world' }
+	  }
+	)
+
+	Store.get_data('mydata') #=> { '1' => { 'hello' => 'world' } }
+	
+## Handling Exceptions
+If your source adapter raises an instance of `SourceAdapterException`, the resulting message will be sent to the client's sync callback(in `@params['error_message']`).  See the rhodes [sync exception handling docs](/rhodes/synchronization#handling-exceptions) for more details.
+
+You can use `SourceAdapterException` as a convenient way to notify your application of various error conditions.
+
+For example, your delete method might check the web service HTTP response code was 200 to make sure the record was deleted:
+
+	:::ruby
+	def delete(delete_hash)   
+	  rest_result = RestClient.delete("#{@base}/#{delete_hash['id']}")
+	  if rest_result.code != 200
+	    raise SourceAdapterException.new("Error deleting record.")
+	  end
+	end
+
+**NOTE: When your adapter method raises an exception, no data is removed from the adapter's master document.**
+
+The following exceptions are provided for convenience:
+
+### `SourceAdapterLoginException`
+Useful to raise in your adapter's login method if it failed.
+
+### `SourceAdapterLogoffException`
+Similar to login, raise this if your adapter's logoff failed.
+
+### `SourceAdapterServerTimeoutException`
+Raise if your backend service connection times out.
+
+### `SourceAdapterServerErrorException`
+Raise this if your backend service returns a non-successful response.
+
+
+## Handling Conflicts
+
+Handling conflicts in RhoConnect follows the same pattern as handling exceptions.  Once your adapter method has detected a conflict, you can raise a `SourceAdapterObjectConflictError` which will be sent to your application's sync callback.
+
+### `SourceAdapterObjectConflictError`
+Raise this if your adapter has detected a conflict.
+
+	:::ruby
+	def update(update_hash) 
+      obj_id = update_hash['id']
+      update_hash.delete('id')   
+      rest_result = RestClient.put("#{@base}/#{obj_id}",:product => update_hash)
+	  if rest_result.code != 200
+	    raise SourceAdapterObjectConflictError.new("Conflict detected updating the object.")
+	  end
+    end
+
+## Sample Adapter
+Here's a complete example of how the completed [product adapter might look](https://github.com/rhomobile/store-server/blob/master/sources/product.rb):
+
+	:::ruby
+	require 'json'
+	require 'rest_client'
+
+	class Product < SourceAdapter
+  
+	  def initialize(source)
+	    @base = 'http://rhostore.heroku.com/products'
+	    super(source)
+	  end
+ 
+	  def query(params=nil)
+    	rest_result = RestClient.get("#{@base}.json").body
+
+		if rest_result.code != 200
+		  raise SourceAdapterException.new("Error connecting!")
+		end
+	    parsed = JSON.parse(rest_result)
+
+	    @result={}
+	    parsed.each do |item|
+	      @result[item["product"]["id"].to_s] = item["product"]
+	    end if parsed   
+	  end
+ 
+	  def create(create_hash)
+	    res = RestClient.post(@base,:product => create_hash)
+    
+	    # After create we are redirected to the new record. 
+	    # We need to get the id of that record and return 
+		# it as part of create so rhoconnect can establish a link 
+		# from its temporary object on the client to this newly 
+		# created object on the server
+	    JSON.parse(
+		  RestClient.get("#{res.headers[:location]}.json").body
+		)["product"]["id"]
+	  end
+ 
+	  def update(update_hash) 
+	    obj_id = update_hash['id']
+	    update_hash.delete('id')   
+	    RestClient.put("#{@base}/#{obj_id}",:product => update_hash)
+	  end
+ 
+	  def delete(delete_hash)   
+	    RestClient.delete("#{@base}/#{delete_hash['id']}")
+	  end
+	end