BaseURL and service endpoint discussion

gistfile1.md

We need to separate the 'base URL' and the service endpoint, when creating new pipes / a new pipeline...

Creating a Pipeline with a pipe

Proposed API

/**
 * A factory method to instantiate the AGPipeline, which
 * contains a RESTful pipe.
 *
 * @param name the name of the first AGPipe object
 * @param baseURL the URL of the server
 * @param endpoint the serivce endpoint, if differs from the pipe name.
 *
 * @return the AGPipeline object
 */
+(id) pipelineWithPipe:(NSString*) name baseURL:(NSURL*)baseURL endpoint:(NSString*)endpoint;

(Note: currently the NSURL type is named 'url', that will be changed to 'baseURL')

Usage:

NSURL* serverURL = [NSURL URLWithString:@"http://todo-aerogear.rhcloud.com/todo-server/"];
AGPipeline* pipeline = [AGPipeline pipelineWithPipe:@"bad name" baseURL:serverURL endpoint:@"projects"]

// get the pipe object for the 'projects' endpoint:
id<AGPipe> myPipe = [pipeline get:@"bad name"];

NSString* url = [myPipe url];

The 'url' is than equivalent to "http://todo-aerogear.rhcloud.com/todo-server/projects/"....

The problem is that there is a 'conflict' between the name and the actual endpoint...

QUESTION: Do we really need a 'logical' name for a pipe, or should the name always be the endpoint ? (At least this is an option for the initial API)

Adding new pipe's (connections) to the Pipeline:

Provide an option to specify an 'endpoint' for a newly added pipe:

/**
 * Adds a new RESTful pipe to the AGPipeline object
 *
 * @param name the name of the actual pipe
 * @param baseURL the URL of the server
 * @param endpoint the serivce endpoint, if differs from the pipe name.
 *
 * @return the new created AGPipe object
 */
-(id<AGPipe>) add:(NSString*) name baseURL:(NSURL*)baseURL endpoint:(NSString*)endpoint;

Similar discussion as above... is the endpoint really needed? Is the name efficient enough (at least for now)?

Also.... in most cases I think a simple 'add' method like below should be really enough:

/**
 * Adds a new RESTful pipe to the AGPipeline object
 *
 * @param name the name of the actual pipe
 *
 * @return the new created AGPipe object
 */
-(id<AGPipe>) add:(NSString*) name;

Here... we 're-use' the given baseURL...

...
// adds a 'task pipe' to the given baseURL
[pipeline add:@"tasks"];

So, here the URL for the 'tasks' pipe would be "http://todo-aerogear.rhcloud.com/todo-server/tasks/"