Nemo Connect

Introduction

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.

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

System Requirements

Nemo Connect requires iOS 7.1 or above. This framework is designed to use ARC.

***

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.

***

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>        
   

2. 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"];
   

3. 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
   

4. And add your signatures there, like this:

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

5. 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
   

6. Fill the plist file as your web service required. More details about the right configuration us up in this page, under the Configuration section.

   

7. 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"];
   

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

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

   

   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.

3. 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;
   

2. Setup the configuration file

   

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

4. Invoke

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

License

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