This framework's main responsibility to download and upload data from an HTTP endpoint, parse, deserialize the data when it is possible and return with the data object. 

The logic behind this approach is to create all the web service related calls and parsing logic in runtime to avoid the code duplication. Each method implementation is generated by the client, based on the plist file which belongs to the category extension.

This version of the library supports iOS 7.1 and above. It's working with the `NSURLSession` approach. Supporting the upload, download and data tasks. For the upload and download there is support to use progress block as optional.

<br />

## Features

### Authentication support
* HTTP BASIC authentication
* Support to modify the network request, for example adding token key
* Clear authentication provider interface to add application specific approach


### Serialization
* JSON top level deserialization with the `NCJSONSerializer`
* Serialization interface, `NCSerializer`

<br />

## System Requirements
Nemo Connect requires **iOS 7.1** or above. This framework is designed to use ARC.

<br />  

## Installation 

### CocoaPods

[CocoaPods](http://cocoapods.org) is a dependency manager, which automates and simplifies the process of using 3rd-party libraries in your projects. To add NemoConnect via CocoaPods, add the following line to your `Podfile`.

```ruby
pod "NemoConnect", "~> 1.0"
```

<br />

***
<br />

## Configuration

### Parameter indicators

We are using special indicators, identifiers to substitute a variable in our method signature into our network request object. The parameter indicator is a special string. We can use parameter indicators in request path, body and header. If the parameter signature in request/path parameter than you have to use % character as prefix.

Parameters must always be `NSObject`. Primitive types like `int`, `float`, `BOOL` are not approved! If you want to pass through just one of your objects property then you can reach that property in this way.

    %OBJECT_INDICATOR_NUMBER[PROPERTY_NAME]


### Parameters

- request
  -  path
  -  method
  -  body
  -  header 
- serialization
  -  serializator
  -  serializedObject

#### Request
Required parameter. All the request parameters like path, method, body will be sorted under it. 

#### Path
Always string value. You can add new request paths in here or you can substitute parameter indicators and this is the point where you can send the GET parameters to your HTTP endpoint.

#### Method
Optional parameter but always in string. Approved values are REST supported HTTP method names (`GET`, `POST`, `DELETE`, `PUT`) The default parameters is `GET`. 

#### Body
Optional parameter. You can only pass `NSData` as a body object. Every request it is only 1 `NSData` object is supported in the parameter list.

#### Header
Optional parameter almost the same as the **Body** parameter. The only different between this one is only approve dictionaries.

#### Serialization
Required only when your network requests response needs to be deserialized. You have to set the serializer class name and the serialized object name. 

#### Serializator
Name of the serializer class. This class must conforms to `NCSerializer` protocol. With the framework we can use the `NCJSONSerializer` as a top level object mapper.

#### SerializedObject
String value, required for deserialization. The target model class name.

<br />
***
<br />

## Usage Examples

Below are some examples how to create an network request. 

The first example shows how to download an image and how to setup the request. The second example will be another network request to request a JSON object with BASIC authentication. In the third example you will see a deserialization example.

### Download Request

1. First, you need to import the framework into you project and import the header file.
    
        #import <Nemo Connect/NemoConnect.h>        

1. Then you have to create an web service instance and setup correctly with the designated initializers.
    
        NSURL *apiURL = [NSURL URLWithString:@"http://HTTP_ENDPOINT"];
        self.webService = [[NCWebService alloc] initWithBaseURL:apiURL processingQueue:self.workingQueue];
        [self.webService setServiceName:@"Image"];

1. The next step will be really important. You have to create a category header file (just the header, the implementation part is not needed anymore) on top of the web service, named like this:

        NCWebService+Image.h

1. And add your signatures there, like this:

        - (NSOperation *)downloadImageWithName:(NSString *)imageName completionBlock:(NCWebServiceCallbackBlock)completionBlock progressBlock:(NCNetworkDownloaderProgressBlock)progressBlock;

1. Then you have to create a plist file and name it the same as you did in the header file, just the extension will be .plist of course. So:

        NCWebService+Image.plist

1. Fill the plist file as your web service required. More details about the right configuration us up in this page, under the **Configuration** section.
 
    <img src="https://s3.amazonaws.com/f.cl.ly/items/0d2a443i0L2y3O0t2l2V/Screen%20Shot%202014-04-24%20at%2014.47.07.png" width="500px" />

1. Then, you have to just invoke this signature from you model manager implementation and you are done.

        [self.webService downloadImageWithName:imageName completionBlock:completionBlock progressBlock:progressBlock];


### Request with Authentication

In this example you have to create the required category header file and plist file pair as you did it in the download example. 

1. First step is to setup a web service instance, create an authentication provider instance.
 
        // create an authentication provider
        NCBasicAuthentication *authenticationProvider = [[NCBasicAuthentication alloc] initWithUsername:@"USERNAME" password:@"PASSWORD"];
        
        // setup web service
        NSURL *apiURL = [NSURL URLWithString:@"http://HTTP_ENDPOINT"];
        self.webService = [[NCWebService alloc] initWithBaseURL:apiURL processingQueue:self.workingQueue authenticationProvider:authenticationProvider];
        [self.webService setServiceName:@"PharmacySearch"];

1. The next step is to create the right method signature and plist file for our network request.

        - (void)searchWithZIPCode:(NSString *)zipCode completionBlock:(NCWebServiceCallbackBlock)completionBlock;

    <img src="https://s3.amazonaws.com/f.cl.ly/items/2Z3A0x3Y3n0h34300z2S/Screen%20Shot%202014-04-24%20at%2015.09.14.png" width="500px" />

    As you can see we are passing one parameter in here cross through the request path as a GET parameter. We marked this parameter indicator %0 - that means the first parameter from the signature. 

1. Invoke your signature

        [self.webService searchWithZIPCode:zipCode completionBlock:^(id data, NSError *const error, NSHTTPURLResponse httpURLResponse) {
             
        }];


### Network Request with Deserialization

Repeat the first steps, create the category header and the plist file. Then setup your web service instance as well.

1. Create your method signature in the header file

        - (NSOperation *)getUsersListWithCompletionBlock:(NCWebServiceCallbackBlock)completionBlock;

1. Setup the configuration file 

    <img src="https://s3.amazonaws.com/f.cl.ly/items/1Q1P2s1K2D2T1I2V1E0j/Screen%20Shot%202014-04-24%20at%2015.18.07.png" width="500px" />

1. Do not forget to create your blue-print object for the deserialization, in this example is the `NDAUser` data model object.

1. Invoke

        [self.webService getUsersListWithCompletionBlock:^(id data, NSError *const error, NSHTTPURLResponse *httpURLResponse) {
             NSLog(@"%@", data);  // this data object will be an NDAUser data object
        }];


<br />

## License

Nemo Connect is released under the MIT license. See LICENSE file for details.

<br >