kborchers/AeroGear.AutoConfig.md

## AeroGear.AutoConfig.md

      
    Raw
  

              AeroGear.AutoConfig.md
            
          
    #AeroGear.AutoConfig
The idea of this utility is to provide a method to automatically configure the client side connections to server resources (Pipeline) via a request for the JSON config to the server from an AeroGear client.
Currently, to set up and use a single connection to the server (pipe) you can use the following:
// Set up a pipeline which contains one pipe using the default REST adapter
var userPipeline = AeroGear.Pipeline( "users" ),
	users = userPipeline.pipes.users;

This is obviously a simplified example so the benefit is not as great but what if you could avoid all of the setup and just do:
var users = AeroGear.Config.users;

Maybe a more complex example would illustrate better:
// Set up a pipeline which contains two pipes using custom settings
var carPipeline = AeroGear.Pipeline({
		name: "oldCars",
		settings: {
			baseURL: "/resources/automobiles/",
			endpoint: "antique",
			recordId: "vin"
		}
	},
	{
		name: "newCars",
		settings: {
			baseURL: "/resources/automobiles/",
			endpoint: "concept",
			recordId: "customId"
		}
	}),
	oldCars = carPipeline.pipes.oldCars,
	newCars = carPipeline.pipes.newCars;

Again, wouldn't it be nice to just be able to go straight to accessing the pipes:
var oldCars = AeroGear.Config.oldCars,
	newCars = AeroGear.Config.newCars;

As you can see, the automatically configured pipes would be namespaced under the AeroGear.Config (name not set in stone) namespace to provide for protection against naming collisions.
In order to do this, what I am proposing is a method to generate a JSON formatted object server-side that the AeroGear client libraries can read and cache which would provide the necessary information to allow the client lib to automatically set up the necessary resources and make them available for use. Below I will describe some of my initial thoughts on how to make this happen which I hope will encourage some good discussion.

##AeroGear.AutoConfig.js
This utility will be kept separate from the main aerogear.js distribution. By doing this, it allows for the act of including the file in the app to be the initiator that "turns on" the functionality.
By default, AeroGear.AutoConfig assumes the config can be found at a REST endpoint named config in the current context of the app. For example, if the app is running at mydomain.com/myapp, AeroGear.AutoConfig will make a request on the initial load of the app to mydomain.com/myapp/config. This endpoint can be customized by setting AeroGear.AutoConfigEndpoint to the custom endpoint after aerogear.js is loaded but before aerogear.autoconfig.js is loaded like this:
<script src="aerogear.js"></script>
<script>AeroGear.AutoConfigEndpoint = "/customConfig";</script>
<script src="aerogear.autoconfig.js"></script>

Discussion - Method for mapping app var names to pipe names generated by the config. This would allow for the use of pipes on the client side while knowing very little about how they are configured. This could be implemented in a subsequent release if at all.
##AeroGear.AutoConfig (iOS)
TODO
##AeroGear.AutoConfig (Android)
TODO

##Config Object
The config could contain a number of items to inform the client of what the server expects.


###Base URL
This is the base URL that should be used with all endpoints. If this is not specified, the client should assume that each endpoint configures its own path.


###Endpoints
Contains an array of key/value pairs of endpoint information.

####Endpoint
An endpoint contains a set of information describing the endpoint to the client so that it can configure itself for the developer. The actual endpoint property can use relative URLs to use the same context as the app, root relative URLs to assume the same domain but override the remainder of the path and then full URLs use that as the path to the endpoint. If a baseURL was specified though, the endpoint is appended to that baseURL in all cases.


Example Config
{
	baseURL: "/resources/automobiles/",
	endpoints: [
		{
		name: "oldCars",
		endpoint: "antique",
		recordId: "vin"
		},
		{
		name: "newCars",
		endpoint: "concept",
		recordId: "customId"
		}
	]
}