rhoconnect 3.4.5 → 4.0.0.beta.10

data/doc/rest-api.txt

@@ -4,7 +4,11 @@ The RhoConnect REST API allows you to control, monitor, and debug a running RhoC
 
 Below we describe the REST API using ruby sample code.
 
+NOTE: All routes that require admin privileges must pass the API token using the special header
+ 	  'X-RhoConnect-API-TOKEN':api_token_string
+
 ## 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
@@ -32,14 +36,10 @@ All API calls will return http 200 and requested data (if applied). Otherwise, A
 	  )
 	end
 
-## API Methods (REST API version 1)
+## System Resource - POST login
 
-NOTE: All routes that require admin privileges must pass the API token using the special header
- 	  'X-RhoConnect-API-TOKEN':api_token_string
-
-### System Resource (requires API token)
+	POST /rc/v1/system/login
 
-#### `POST /rc/v1/system/login`
 Before you can use RhoConnect API you should login to the RhoConnect server and get API token:
 
 	:::ruby
@@ -52,7 +52,10 @@ Before you can use RhoConnect API you should login to the RhoConnect server and
 
 	@api_token = RestClient.post("#{server}/rc/v1/system/login", { :login => login, :password => password }.to_json, :content_type => :json)
 
-#### `GET /rc/v1/system/license`
+## System Resource - GET license
+
+	GET /rc/v1/system/license
+
 Returns license information of the currently used license
 
 	:::ruby
@@ -61,7 +64,10 @@ Returns license information of the currently used license
       {'X-RhoConnect-API-TOKEN' => @api_token}
     ).body
 
-#### `POST /rc/v1/system/reset`
+## System Resource - POST reset
+
+	POST /rc/v1/system/reset
+
 Reset the server: flush db and re-bootstrap server
 
 	:::ruby
@@ -71,7 +77,10 @@ Reset the server: flush db and re-bootstrap server
 	   'X-RhoConnect-API-TOKEN' => @api_token}
     )
 
-#### `GET /rc/v1/system/appserver`
+## System  Resource - GET appserver
+
+	GET /rc/v1/system/appserver
+
 Returns the url of the plugin's backend from the RhoConnect server.
 
 	:::ruby
@@ -80,7 +89,10 @@ Returns the url of the plugin's backend from the RhoConnect server.
       {'X-RhoConnect-API-TOKEN' => @api_token}
     ).body
 
-#### `POST /rc/v1/system/appserver`
+## System Resource - POST appserver
+
+	POST /rc/v1/system/appserver
+
 Saves the url of the plugin's backend to the RhoConnect server.
 
 	:::ruby
@@ -93,18 +105,17 @@ Saves the url of the plugin's backend to the RhoConnect server.
        'X-RhoConnect-API-TOKEN' => @api_token}
     )
 	
-#### `GET /rc/v1/system/stats`
+## System Resource - GET stats
+
+	GET /rc/v1/system/stats
+
 Retrieves stats for a given metric key:
 
 	:::ruby
 	RestClient.get(
 	  "#{server}/rc/v1/system/stats", 
 	  { 
-		:params => {:metric => 'foo', 
-					:start => 0, 
-					:finish => -1} 
-	  },
-	  {
+		:params => {:metric => 'foo', :start => 0, :finish => -1},
 		'X-RhoConnect-API-TOKEN' => @api_token
 	  }
 	)
@@ -115,16 +126,15 @@ Retrieves a list of metric keys matching a given pattern.  This supports 'glob'
 	RestClient.get(
 	  "#{server}/rc/v1/system/stats", 
 	  { 
-		:params => {:names => 'sources:*:Product'}
-	  },
-	  {
+		:params => {:names => 'sources:*:Product'},
 		'X-RhoConnect-API-TOKEN' => @api_token
 	  }
 	)
-	
-### Store Resource (requires API token)
 
-#### `GET /rc/v1/store/:doc`
+## Store Resource - GET doc
+
+	GET /rc/v1/store/:doc
+
 Return content of a given document stored in Redis.
 
 	:::ruby
@@ -135,7 +145,10 @@ Return content of a given document stored in Redis.
 	  }
 	).body
 
-#### `POST /rc/v1/store/:doc`
+## Store Resource - POST doc
+
+	POST /rc/v1/store/:doc
+
 Sets the content of the specified server document. Data should be either a string or hash of hashes.
 If `append` flag is set to `true` , the data is appended to the current doc (if it exists) instead of replacing it.
 
@@ -150,9 +163,10 @@ If `append` flag is set to `true` , the data is appended to the current doc (if
 	   'X-RhoConnect-API-TOKEN' => @api_token}
     )
 
-### User Resource (requires API token)
+## User Resource - POST user
+
+	POST /rc/v1/users
 
-#### `POST /rc/v1/users`
 Create a user in this RhoConnect application.
 
 	:::ruby
@@ -167,7 +181,10 @@ Create a user in this RhoConnect application.
 	   'X-RhoConnect-API-TOKEN' => @api_token}
 	)
 
-#### `DELETE /rc/v1/users/:user_id`
+## User Resource - DELETE user_id
+
+	DELETE /rc/v1/users/:user_id
+
 Delete User and all associated devices from the RhoConnect application.
 
 	:::ruby
@@ -178,7 +195,10 @@ Delete User and all associated devices from the RhoConnect application.
 	  }
 	)
 
-#### `PUT /rc/v1/users/:user_id`
+## User Resource - PUT user_id
+
+	PUT /rc/v1/users/:user_id
+
 Update attributes for a user on this RhoConnect application.
 
 	:::ruby
@@ -193,7 +213,10 @@ Update attributes for a user on this RhoConnect application.
 	   'X-RhoConnect-API-TOKEN' => @api_token}
 	)
 
-#### `GET /rc/v1/users`
+## User Resource - GET users
+
+	GET /rc/v1/users
+
 List users registered with this RhoConnect application.
 
 	:::ruby
@@ -204,7 +227,10 @@ List users registered with this RhoConnect application.
 	  }
     ).body
 
-#### `GET /rc/v1/users/:user_id`
+## User Resource - GET user_id
+
+	GET /rc/v1/users/:user_id
+
 Returns the information for the specified user.
 
 	:::ruby
@@ -215,7 +241,10 @@ Returns the information for the specified user.
 	  }
 	).body
 
-#### `GET /rc/v1/users/:user_id/clients`
+## User Resource - GET clients
+
+	GET /rc/v1/users/:user_id/clients
+
 List clients (devices) associated with given user.
 
 	:::ruby
@@ -227,7 +256,10 @@ List clients (devices) associated with given user.
 
 Returns list of client ids.
 
-#### `DELETE /rc/v1/users/:user_id/clients/:client_id`
+## User Resource - DELETE client_id
+
+	DELETE /rc/v1/users/:user_id/clients/:client_id
+
 Deletes the specified client (device) for the given user.
 
 	:::ruby
@@ -238,7 +270,10 @@ Deletes the specified client (device) for the given user.
 	  }
     )    
 
-#### `GET /rc/v1/users/:user_id/sources/:source_id/docnames`
+## User Resource - GET source_id docnames
+
+	GET /rc/v1/users/:user_id/sources/:source_id/docnames
+
 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. 
@@ -251,8 +286,10 @@ If `:user_id` set to '*', this call will return list of keys for 'shared' docume
 	  }
 	).body
 
+## User Resource - POST ping
+
+	POST /rc/v1/users/ping
 
-#### `POST /rc/v1/users/ping`
 Sends PUSH message to all devices of the specified user(s):
 
 	:::ruby
@@ -276,7 +313,10 @@ Sends PUSH message to all devices of the specified user(s):
 		'X-RhoConnect-API-TOKEN' => @api_token }
 	) 
 
-#### `GET /rc/v1/users/:user_id/sources/:source_id/docs/:doc`
+## User Resource - GET source_id doc
+
+	GET /rc/v1/users/:user_id/sources/:source_id/docs/:doc
+
 Return content of a given source document for the specified user.
 
 	:::ruby
@@ -287,7 +327,10 @@ Return content of a given source document for the specified user.
 	  }
 	).body
 
-#### `POST /rc/v1/users/:user_id/sources/:source_id/docs/:doc`
+## User Resource - POST source_id doc
+
+	POST /rc/v1/users/:user_id/sources/:source_id/docs/:doc
+
 Sets the content of the specified source document for the given user. Data should be either a string or hash of hashes.
 If `append` flag is set to `true` , the data is appended to the current doc (if it exists) instead of replacing it.
 
@@ -302,9 +345,10 @@ If `append` flag is set to `true` , the data is appended to the current doc (if
 	   'X-RhoConnect-API-TOKEN' => @api_token}
     )
 
-### Read State Resource (requires API token)
+## Read State - POST user source_id
+
+	POST /rc/v1/read_state/users/:user_id/sources/:source_id
 
-#### `POST /rc/v1/read_state/users/:user_id/sources/:source_id`
 Sets source poll interval to "current time plus x seconds".
 
 	:::ruby
@@ -319,9 +363,10 @@ Sets source poll interval to "current time plus x seconds".
 
 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.
 
-### Source Controller (requires API token)
+## Source Controller - GET partition_type
+
+	GET /rc/v1/sources/type/:partition_type
 
-#### `GET /rc/v1/sources/type/:partition_type`
 Return list of source adapters for this RhoConnect application for the given partition type.
 Partition type can be either `app` or `user`.
 
@@ -332,7 +377,10 @@ Partition type can be either `app` or `user`.
 	  }
 	).body
 
-#### `GET /rc/v1/sources/:source_id`
+## Source Controller - GET source_id
+
+	GET /rc/v1/sources/:source_id
+
 Return attributes associated with a given source:
 
 * `name` - name of the data source
@@ -352,7 +400,10 @@ Return attributes associated with a given source:
 	  }
 	).body
 
-#### `PUT /rc/v1/sources/:source_id`
+## Source Controller - PUT source_id
+
+	PUT /rc/v1/sources/:source_id
+
 Updates attributes associated with a given 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.
@@ -367,10 +418,11 @@ Updates attributes associated with a given source:
 	   'X-RhoConnect-API-TOKEN' => @api_token}
 	).body
 
-### Client Resource (requires API token)
+## Client Resource - GET client_id
+
+	GET /rc/v1/clients/:client_id
 
-#### `GET /rc/v1/clients/:client_id`
-Returns client (device) attributes, such as `device_type`, `device_pin`, `device_port`. These attributes used by [RhoConnect push](/rhoconnect/push). 
+Returns client (device) attributes, such as `device_type`, `device_pin`, `device_port`. These attributes are used by [RhoConnect push](/rhoconnect/push). 
 
 	:::ruby
 	client_attributes = RestClient.get(
@@ -380,7 +432,10 @@ Returns client (device) attributes, such as `device_type`, `device_pin`, `device
 	  }
 	).body
 
-#### `GET /rc/v1/clients/:client_id/sources/:source_id/docnames`
+## Client Resource - GET source_id docnames
+
+	GET /rc/v1/clients/:client_id/sources/:source_id/docnames
+
 Returns list of document keys associated with particular client for a given source. These documents are used by the server to sync data with the client. 
 
 	:::ruby
@@ -391,7 +446,10 @@ Returns list of document keys associated with particular client for a given sour
 	  }
 	).body
 
-#### `GET /rc/v1/clients/:client_id/sources/:source_id/docs/:doc`
+## Client Resource - GET source_id doc
+
+	GET /rc/v1/clients/:client_id/sources/:source_id/docs/:doc
+
 Return content of a given source document for the specified client.
 
 	:::ruby
@@ -402,7 +460,10 @@ Return content of a given source document for the specified client.
 	  }
 	).body
 
-#### `POST /rc/v1/clients/:client_id/sources/:source_id/docs/:doc`
+## Client Resource - POST source_id doc
+
+	POST /rc/v1/clients/:client_id/sources/:source_id/docs/:doc
+
 Sets the content of the specified source document for the given client. Data should be either a string or hash of hashes.
 If `append` flag is set to `true` , the data is appended to the current doc (if it exists) instead of replacing it.
 
@@ -417,11 +478,11 @@ If `append` flag is set to `true` , the data is appended to the current doc (if
 	   'X-RhoConnect-API-TOKEN' => @api_token}
     )
 
+## Plugin source_name - POST push_objects
 
-### Plugin methods (requires API token)
+	POST /app/v1/:source_name/push_objects
 
-#### `POST /app/v1/:source_name/push_objects`
-Push new objects or object updates to RhoConnect. These changes will be sent to device next time it synchronizes.
+Push new objects or object updates to RhoConnect. These changes will be sent to the device the next time it synchronizes.
 
 **NOTE: you may use [ping](/rhoconnect/push) to notify client and trigger sync.**
 
@@ -447,7 +508,10 @@ documents, `push_objects` method can be optimized by invoking only the necessary
 the number of transactions with Redis. To force the optimization, user can use the `:rebuild_md => false` flag
 in the `push_objects` parameters hash.**
 
-#### `POST /app/v1/:source_name/push_deletes`
+## Plugin source_name - POST delete_objects
+
+	POST /app/v1/:source_name/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.**
@@ -469,7 +533,10 @@ documents, `push_deletes` method can be optimized by invoking only the necessary
 the number of transactions with Redis. To force the optimization, user can use the `:rebuild_md => false` flag
 in the `push_deletes` parameters hash.**
 
-#### `POST /app/v1/:source_name/fast_insert`
+## Plugin sourece_name - POST fast_insert
+
+	POST /app/v1/:source_name/fast_insert
+
 Push new objects to RhoConnect. Changes are inserted into the Redis set without any checking for previous existence.
 This way, the insert is very fast, but user must ensure that the object didn't exist before. No safeguards are implemented. 
 Use this method only when you can ensure the integrity of the data.
@@ -493,7 +560,10 @@ Use this method only when you can ensure the integrity of the data.
 	   'X-RhoConnect-API-TOKEN' => @api_token}
 	)
 	
-#### `POST /app/v1/:source_name/fast_update`
+## Plugin source_name - POST fast_update
+
+	POST /app/v1/:source_name/fast_update
+
 Push object updates to RhoConnect. This method doesn't involve pulling the existing data out of Redis. Instead it required user to provide the previous state of the data. This way, this method allows for very fast updates (since it just removes the previous data from set and adds new ones). However, no data integrity checks are performed. Therefore, this method must be used only if user can ensure the integrity of the data (i.e. previous state must exist, otherwise it won't be properly deleted). Also, this method can be used to perform fast appends and deletes for any of the object's attributes (However, you shouldn't use this method to remove all of the attributes, `fast_delete` should be used instead.)
 
 **NOTE: you may use [ping](/rhoconnect/push) to notify client after the update and trigger sync.**
@@ -524,8 +594,11 @@ Push object updates to RhoConnect. This method doesn't involve pulling the exist
 	   'X-RhoConnect-API-TOKEN' => @api_token}
 	)
 
-#### `POST /app/v1/:source_name/fast_delete`
-Push object deletes to RhoConnect. This method doesn't involve pulling the existing data out of Redis and removing all of its attributes. Instead it required user to provide all of the object's data in the hash to be removed. This way, this method allows for very fast deletes (since it just removes the object's data from set). However, no data integrity checks are performed. Therefore, this method must be used only if user can ensure the integrity of the data (i.e. supply all of the object's data to be removed, otherwise some object's data will remain in Redis).
+## Plugin source_name - POST fast_delete
+
+	POST /app/v1/:source_name/fast_delete
+
+Push object deletes to RhoConnect. This method doesn't involve pulling the existing data out of Redis and removing all of its attributes. Instead it requires the user to provide all of the object's data in the hash to be removed. This way, this method allows for very fast deletes (since it just removes the object's data from set). However, no data integrity checks are performed. Therefore, this method must be used only if user can ensure the integrity of the data (i.e. supply all of the object's data to be removed, otherwise some object's data will remain in Redis).
 
 **NOTE: you may use [ping](/rhoconnect/push) to notify client after the delete and trigger sync.**
 

data/doc/rhoconnect-redis-stack.txt

@@ -288,6 +288,126 @@ The template will create a sample scalable rhoconnect stack with 2 elastic load
 * 2 EC2 instances of monitor servers (Haproxy/Monit) 
 * 2 EC2 instances of redis servers (master/slave)
 
+## Setting up Redis Servers Horizontal Scaling
+
+Under heavy load single Redis server might be a bottleneck in RhoConnect stack performance due to high network traffic, 
+large memory footprints of stored data in server instance. To address redis server performance issues RhoConnect (>= v4.0.0)
+ supports multiple Redis instances per app, and evenly distributing load across available Redis server instances. 
+
+### Configure RhoConnect app to support multiple Redis instances
+
+Edit your app `settings/settings.yml` file and replace :redis one liner by array of redis servers you are going to use: 
+
+	:::yaml
+	# ...
+	:production: 
+	  :licensefile: settings/license.key
+	  :syncserver: http://localhost:9292/api/application/
+	  :push_server: http://appname:secret@localhost:8675/
+	  # Two or more redis servers per app 
+	  :redis:
+	    - localhost:6379
+	    - localhost:6380
+	    - localhost:6381
+	    - localhost:6382
+	    # ...
+
+
+### Create a custom Amazon Image with multiple Redis instances
+
+The following recommendations are based on Ubuntu Amazon image, where [RhoConnect Redis](http://docs.rhomobile.com/rhoconnect/deploying#deploying-rhoconnect-redis-and-push-packages-on-linux-servers) package installed and you wanted host 4 redis instances on ports 6379, 6380, 6381, and 6382 respectively. 
+
+Rename `/opt/rhoconnect/etc/redis.conf` configuration file to `/opt/rhoconnect/etc/redis-6379.conf` and make sure that it has settings for the 1st instance: 
+
+	:::text
+	...
+	daemonize yes
+	pidfile /var/run/redis/redis6379.pid
+	port 6379
+
+	# DO NOT FORGET comment persistence cmds
+	# save ...
+	...
+
+For other servers create `/opt/rhoconnect/etc/redis-6380.conf`, `/opt/rhoconnect/etc/redis-6381.conf` and `/opt/rhoconnect/etc/redis-6382.conf` 
+ files and do similar setting for corresponding redis instances: 
+
+	:::text
+	# File /opt/rhoconnect/etc/redis-6380.conf
+	...
+	daemonize yes
+	pidfile /var/run/redis/redis6380.pid
+	port 6380
+	# DO NOT FORGET comment persistence cmds
+	...
+
+	# File /opt/rhoconnect/etc/redis-6381.conf
+	...
+	daemonize yes
+	pidfile /var/run/redis/redis6381.pid
+	port 6381
+	# DO NOT FORGET comment persistence cmds
+	...
+	
+	# File /opt/rhoconnect/etc/redis-6382.conf
+	...
+	daemonize yes
+	pidfile /var/run/redis/redis6382.pid
+	port 6382
+	# DO NOT FORGET comment persistence cmds
+	...
+
+
+Delete `/etc/init/rhoconnect-redis.conf` file if it's there.
+Create upstart script `/etc/init/rhoconnect-redis-6379.conf` for the 1-st instance:
+
+	:::text
+	# /etc/init/rhoconnect-redis-6379.conf 
+	
+	description "Redis Datastore Server"
+	# Redis is a key value in memory persistent datastore
+
+	start on (local-filesystems and runlevel [2345])
+	stop on runlevel [016]
+	expect fork
+	respawn
+
+	pre-start script
+	  mkdir -p /var/run/redis
+	  chown redis:redis /var/run/redis
+	end script
+
+	exec start-stop-daemon --start --chuid redis:redis --pidfile /var/run/redis/redis6379.pid --umask 007 \ 
+	--exec  /opt/rhoconnect/bin/redis-server -- /opt/rhoconnect/etc/redis-6379.conf
+
+Define upstart scripts `/etc/init/rhoconnect-redis-6380.conf`, `/etc/init/rhoconnect-redis-6381.conf`, and `/etc/init/rhoconnect-redis-6382.conf`  for other instances:
+
+	:::text
+	# /etc/init/rhoconnect-redis-6380.conf
+	# ...
+	exec start-stop-daemon --start --chuid redis:redis --pidfile /var/run/redis/redis6380.pid --umask 007  \
+	--exec /opt/rhoconnect/bin/redis-server -- /opt/rhoconnect/etc/redis-6380.conf
+
+	# /etc/init/rhoconnect-redis-6381.conf
+	# ...
+	exec start-stop-daemon --start --chuid redis:redis --pidfile /var/run/redis/redis6381.pid --umask 007  \
+	--exec /opt/rhoconnect/bin/redis-server -- /opt/rhoconnect/etc/redis-6381.conf
+
+	# /etc/init/rhoconnect-redis-6382.conf
+	# ...
+	exec start-stop-daemon --start --chuid redis:redis --pidfile /var/run/redis/redis6382.pid --umask 007  \
+	--exec /opt/rhoconnect/bin/redis-server -- /opt/rhoconnect/etc/redis-6382.conf
+
+		
+We provide a public preconfigured image with above settings for Us `West N. California` region:	
+
+* `ami-94b496d1` (Redis-Server-2.6.7 with 4 instances on ports 6379, 6380, 6381, and 6382)
+
+### Amazon CloudFormation Template File
+
+This Amazon CloudFormation [template file](https://s3.amazonaws.com/rhoconnect-deploy/rhoconnect-template-2-redises-4-instances.txt)
+ shows how 2 redis servers with 4 instances per server might be used for a typical rhoconncect application.
+
 
 
 

data/doc/settings.txt

@@ -11,12 +11,12 @@ Each of the environment categories must have the following entries:
 	
 	:::yaml
 	:syncserver: <url>
-	:redis: <url>
+	:redis: <url|array_of_urls>
 	:licensefile: <filename>
 
 `:syncserver`: application's base url.
 
-`:redis`: Redis url.
+`:redis`: Redis url. Can be specified as an Array of URLs. In that case, RhoConnect will use several Redis servers (this can be used in case of high-volume data)
 
 `:licensefile`: application's license file.
 
@@ -28,9 +28,7 @@ In addition, you can specify the following settings:
 	:redis_timeout: <secs>
 	:poll_interval_default: <secs>
 	:bulk_sync_poll_interval: <secs>
-	:c2dm_username: <google's email>
-	:c2dm_passwd: <passwd>                       
-	:authtoken: <authtoken>
+	:gcm_api_key: your_gcm_api_key_here
 
 `:connection_pool_size`: By default, RhoConnect maintains multiple concurrent connections to Redis organized in Connection Pool. This setting allows you to specify the size of the pool. By default, RhoConnect starts with five (5) Redis connections.
 
@@ -42,13 +40,7 @@ In addition, you can specify the following settings:
 
 `:bulk_sync_poll_interval`: poll interval setting for bulk data sync, in seconds.
 
-`:c2dm_username`: The email address for the C2DM Google account.
-
-`:c2dm_passwd`: The password for the C2DM Google account.
-
-`:authtoken`: these settings are used specifically for Android push notifications. In order to push messages to the Android device, your server needs to obtain Google's C2DM authentication token associated with the trusted google account. For this purpose, you can specify C2DM Google account's username/password combo via the `:c2dm_username` and `:c2dm_passwd` settings. At run-time, the system will use these credentials to obtain the C2DM token and store it in the Redis for the future use. Once the token is expired, the system will automatically connect to the Google C2DM service to renew the token.
-
-Alternatively, you can use the `:authtoken` setting to specify the pre-defined authentication token. This token MUST be related to the role-based google account registered for your application. See [the rhodes push instructions](/rhodes/device-caps#push-notifications) for more details. To retrieve this token, use sample script [c2dm.rb](http://github.com/rhomobile/rhodes/blob/master/bin/c2dm.rb). Uncomment last two lines and put your google account specific data, then run it. It will print token to stdout. This approach, however, will not allow the server to connect to the C2DM service and renew the token once it is expired.
+`:gcm_api_key`: The [API key for Google Cloud Messaging](/rhoconnect/push-client-setup-android#setting-up-android-google-cloud-messaging).
 
 ## Source settings
 

data/doc/source-adapters-intro.txt

@@ -0,0 +1,28 @@
+RhoConnect Source Adapters
+===
+
+## What is RhoConnect Source Adapter?
+
+A RhoConnect Source Adapter is a software entity which encapsulates:
+
+* Source's business logic implementation (via a Model)
+* Source's run-time management and HTTP route handling (via a Controller)
+
+## Source Adapter Controller
+
+From a web developer's point of view - each RhoConnect application is a collection of unique HTTP route handlers grouped logically into a Source Adapter Controller.
+Each Source Adapter Controller defines a serviceable end point relative to the root of the application and represents itself as a stand-alone [Sinatra](http://www.sinatrarb.com/) app.
+As a Sinatra app - Source Adapter Controller defines the available routes and handles the incoming requests.
+Typically, you will just re-use the default implementation of the Controller. However, in some cases, you may customize it by adding your own routes or altering the default route's behaviour. In this sense, Controller is still a Sinatra app - and you can re-use any of the available Sinatra tools and techniques.
+
+## Source Adapter Model
+
+By default, each RhoConnect Source Adapter Controller defines SYNC routes to be called by the RhoConnect client's application.
+At run-time, the Source Adapter controller prepares the context of the request (for example, parses and prepares the query parameters, etc.), then instantiates the corresponding RhoConnect Source Adapter Model and calls its methods.
+
+As a developer - you will need to implement the business logic inside of the RhoConnect Source Adapter Model class.
+Connecting to a backend service with RhoConnect means that you will be required to write a small amount of code for the query, create, update and delete operations of your particular enterprise backend. In this way - the RhoConnect Source Adapter model is a collection of Ruby code to access and process the data from your enterprise backend.
+
+## Source Adapter API
+
+Starting with RhoConnect 4, Source Adapters can be developed in Ruby or JavaScript.  The next sections describe the Source Adapter API available for each of these languages.