App42 Cloud API

iOS cloud SDK

Catalogue

This Service provides a complete cloud based catalogue management. An app can keep all its items based on category on the Cloud. This service provides several utility methods to manage catalogue on the cloud. One can add items with its related information in a particular category. And there can be several categories in a catalogue. The App developer can create several catalogues if needed. The Cart service can be used along with Catalogue service to create an end to end Shopping feature for a Mobile and Web App.

In order to use the various functions available under a particular API, a developer will have to create an instance of ServiceAPI by passing the apiKey and the secretKey which has been received while creating an app.

ServiceAPI *serviceAPIObj = [[ServiceAPI alloc]init];
serviceAPIObj.apiKey = @"<API_KEY>";
serviceAPIObj.secretKey = @"<SECRET_KEY>";	

After initialization, developer needs to call the buildXXXService method on ServiceAPI instance to get the instance of the particular API that you wish to build. For example, To build an instance of CatalogueService, buildCatalogueService() method needs to be called.

	CatalogueService *catalogueService = [serviceAPIObj buildCatalogueService];

Once the API instance has been retrieved, You are ready to use the functions available for that particular API.

The methods available under a particular API will return the domain object (like Catalogue in this case) as a response which will have the accessor / mutator to access the available properties for that object. You can get the response in the form of JSON as well. We have provided the JSON response with every function detail which can be retrieved by calling the toString() on the returned object.

NSString *catalogueName =  @"CatalogueName"; 
NSString *catalogueDescription =  @"CatalogueName"; 

Catalogue *catalogue = [catalogueService createCatalogue:catalogueName catalogueDescription:catalogueDescription]; /* returns the Catalogue object. */ 
NSLog(@"name is = %@",catalogue.name);
NSLog(@"description is = %@",catalogue.description);
NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. */ 
                            

The functions available under Catalogue API can throw some exceptions in abnormal conditions. Example of the same has been given below.

E.g. If App developer is creating a category under the catalogue which is not in database, the function will throw the App42Exception (as shown below) with message as "Not Found" and the appErrorCode as "3401" and the details as "Catalogue by the name '<catalogueName>' does not exist".

NSString *catalogueName =  @"CatalogueName01"; 
NSString *categoryName =  @"CategoryName01"; 
NSString *categoryDescription =  @"CategoryDescription";

@try{
	Catalogue *catalogue = [catalogueService createCategory:catalogueName categoryName:categoryName categoryDescription:categoryDescription]; /* returns the Catalogue object. */ 
} @catch(App42Exception *ex) {
	int appErrorCode = ex.appErrorCode;
	int httpErrorCode = ex.httpErrorCode;
	if(appErrorCode == 3401)
	{
		// Handle here for Not Found (Catalogue by the name '<catalogueName>' does not exist.)
	}
	else if(appErrorCode  == 3402)
	{
		// Handle here for Bad Request (The request parameters are invalid. Category by the name '<categoryName>' for the Catalogue by the name '<categoryName>' already exists.)
	}
	else if(appErrorCode == 1401)
	{
		// handle here for Client is not authorized
	}
	else if(appErrorCode == 1500)
	{
		// handle here for Internal Server Error
	}
	NSString *jsonText = ex.reason; /* returns the Exception text in JSON format. (as shown below)*/	
}
                            
	{
		"app42Fault": {
			"httpErrorCode": 404,
			"appErrorCode": 3401,
			"message": "Not Found",
			"details": "Catalogue by the name 'CatalogueName01' does not exist"
		}
	}							

Below are the HTTP Error Codes and their description, the function under the Catalogue API can throw.

							
/*
1400 - BAD REQUEST - The Request parameters are invalid
1401 - UNAUTHORIZED - Client is not authorized
1500 - INTERNAL SERVER ERROR - Internal Server Error. Please try again	
*/						

Below are the Application Error Codes and their description, the function under the Catalogue API can throw.

/*
3400 - BAD REQUEST - The request parameters are invalid. Catalogue by the name '<catalogueName>' already exists.
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
3402 - BAD REQUEST - The request parameters are invalid. Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' already exists.
3403 - NOT FOUND - Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' does not exist.
3404 - BAD REQUEST - The request parameters are invalid. Item with the id '<itemId>' for the Category by the name '<categoryName>' and Catalogue by the name '<catalogueName>' already exists.
3405 - NOT FOUND - Item with the id '<itemId>' for the Category by the name '<categoryName>' and Catalogue by the name '<catalogueName>' does not exist.
3406 - NOT FOUND - Item with the id '<itemId>' does not exist.
3407 - NOT FOUND - The number of items for category by the name '<categoryName>' for Catalogue by the name '<catalogueName>' are less than the specified offset : <offset>.
*/							

Various functions available under Catalogue API has been explained below.

-(Catalogue*)createCatalogue:(NSString*)catalogueName catalogueDescription:(NSString*)catalogueDescription

Creates a Catalogue for a particular App. Categories can be added to the Catalogue.

Parameters:

catalogueName - Name of the Catalogue to be created
catalogueDescription - Description of the catalogue to be created

Returns:

Catalogue object

Response: Catalogue Object

Exception:

This method throws following exception.
/*
3400 - BAD REQUEST - The request parameters are invalid. Catalogue by the name '<catalogueName>' already exists.
*/ 	    
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
String catalogueDescription = "CatalogueName";
Catalogue *catalogue = [catalogueService createCatalogue:catalogueName catalogueDescription:catalogueDescription]; /* returns the Catalogue object. */ 
NSLog(@"catalogueName is = %@" catalogue.name);
NSLog(@"catalogueDescription is = %@",catalogue.description);
NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. (as shown below)*/    
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "description": "CatalogueName"
                }
            }
        }
    }
} 
-(Catalogue*)createCategory:(NSString*)catalogueName categoryName:(NSString*)categoryName categoryDescription:(NSString*)categoryDescription

Creates a Category for a particular Catalogue e.g. Books, Music etc.

Parameters:

catalogueName - Name of the Catalogue for which Category has to be created
categoryName - Name of the Category that has to be created
categoryDescription - Description of the category to be created

Returns:

Catalogue object containing created category information

Response: Catalogue Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
3402 - BAD REQUEST - The request parameters are invalid. Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' already exists.
*/ 	      
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
NSString *catalogueDescription = @"CatalogueName";
Catalogue *catalogue = [catalogueService createCategory:catalogueName categoryName:categoryName categoryDescription:categoryDescription]; /* returns the Catalogue object. */ 
NSString *catalogueName =  catalogue.name; 
NSMutableArray *categoryList = catalogue.categoryListArray;
for(CategoryData *category in categoryList)
{
	NSLog(@"name is = %@",category.name);
	NSLog(@"description is = %@",category.description);
} 
NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. */  (as shown below)*/
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "categories": {
                        "category": {
                            "name": "CategoryName01",
                            "description": "CategoryDescription"
                        }
                    }
                }
            }
        }
    }
} 
-(Catalogue*)addItem:(NSString*)catalogueName categoryName:(NSString*)categoryName itemData:(ItemData*)itemData

Creates a Item in a Category for a particular Catelogue.

Parameters:

catalogueName - Name of the Catalogue to which item has to be added
categoryName - Name of the Category to which item has to be added
itemData - Item Information that has to be added

Returns:

Catalogue object containing added item.

Response: Catalogue Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
3403 - NOT FOUND - Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' does not exist.
3404 - BAD REQUEST - The request parameters are invalid. Item with the id '<itemId>' for the Category by the name '<categoryName>' and Catalogue by the name '<catalogueName>' already exists.
*/ 		 
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
NSString *categoryName = @"CategoryName01";
ItemData itemData = [[ItemData alloc]init];
itemData.description = @"Pic";
itemData.image = [[NSBundle mainBundle]pathForResource:@"Flowers" ofType:@"jpg"];
itemData.itemId = @"abc1234007";
itemData.name = @"Item";
itemData.price = 20.0;				

Catalogue *catalogue = [catalogueService addItem:catalogueName categoryName:categoryName itemData:itemData]; /* returns the Catalogue object. */ 
NSString *catalogueName =  catalogue.name; 
NSMutableArray *categoryList = catalogue.categoryListArray;
for(CategoryData *category in categoryList)
{
	NSLog(@"name is = %@",category.name);
	NSLog(@"description is = %@",category.description);
	NSMutableArray *itemList = category.itemListArray;
	for (categoryItem *item in itemList)
	{
		NSLog(@"price is = %f",item.price);
		NSLog(@"itemId is = %@",item.itemId);
		NSLog(@"name is = %@",item.name);
	}  
} 
NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. */ (as shown below)*/
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "categories": {
                        "category": {
                            "name": "CategoryName01",
                            "items": {
                                "item": {
                                    "itemId": "ItemId01",
                                    "name": "ItemName01",
                                    "description": "ItemDescription01",
                                    "url": "http://XXXXX.jpg",
                                    "tinyUrl": "http://tinyurl.com/cgjm9c7",
                                    "price": 200
                                }
                            }
                        }
                    }
                }
            }
        }
    }
} 
-(Catalogue*)getItems:(NSString*)catalogueName

Fetches all items for a Catalogue.

Parameters:

catalogueName - Name of the Catalogue from which item has to be fetched

Returns:

Catalogue object containing all Items

Response: Catalogue Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
*/ 		       
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
Catalogue *catalogue = [catalogueService getItems:catalogueName]; /* returns the Catalogue object. */ 
NSLog(@"catalogueName =  %@",catalogue.name); 
NSMutableArray *categoryList = catalogue.categoryListArray;
for(CategoryData *category in categoryList)
{
	NSLog(@"name is = %@",category.name);
	NSLog(@"description is = %@",category.description);
	NSMutableArray *itemList = category.itemListArray;
	for (categoryItem *item in itemList)
	{
		NSLog(@"price is = %f",item.price);
		NSLog(@"itemId is = %@",item.itemId);
		NSLog(@"name is = %@",item.name);
	}  
} 
NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. */  (as shown below)*/
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "categories": {
                        "category": {
                            "name": "CategoryName01",
                            "items": {
                                "item": [
                                    {
                                        "itemId": "ItemId01",
                                        "name": "ItemName01",
                                        "description": "ItemDescription01",
                                        "url": "http://XXXXX.jpg",
                                        "tinyUrl": "http://tinyurl.com/bqhj3c9",
                                        "price": 200
                                    },
                                    {
                                        "itemId": "Item4",
                                        "name": "ItemName02",
                                        "description": "Description",
                                        "url": "http://XXXXX.jpg",
                                        "tinyUrl": "http://tinyurl.com/cbhorhl",
                                        "price": 20
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        }
    }
} 
-(Catalogue*)getItemsByCategory:(NSString*)catalogueName categoryName:(NSString*)categoryName

Fetches all items for a Catalogue and Category.

Parameters:

catalogueName - Name of the Catalogue from which item has to be fetched
categoryName - Name of the Category from which item has to be fetched

Returns:

Catalogue object

Response: Catalogue Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
3403 - NOT FOUND - Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' does not exist.
*/ 		        
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
NSString *categoryName = @"CategoryName01";	
Catalogue *catalogue = [catalogueService getItemsByCategory:catalogueName categoryName:categoryName]; /* returns the Catalogue object. */ 
NSLog(@"catalogueName =  %@",catalogue.name); 
NSMutableArray *categoryList = catalogue.categoryListArray;
for(CategoryData *category in categoryList)
{
	NSLog(@"name is = %@",category.name);
	NSLog(@"description is = %@",category.description);
	NSMutableArray *itemList = category.itemListArray;
	for (categoryItem *item in itemList)
	{
		NSLog(@"price is = %f",item.price);
		NSLog(@"itemId is = %@",item.itemId);
		NSLog(@"name is = %@",item.name);
	}  
}
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "categories": {
                        "category": {
                            "name": "CategoryName01",
                            "items": {
                                "item": [
                                    {
                                        "itemId": "ItemId01",
                                        "name": "ItemName01",
                                        "description": "ItemDescription01",
                                        "url": "http://XXXXX.jpg",
                                        "tinyUrl": "http://tinyurl.com/brrh7dr",
										"price": 200
                                    },
                                    {
                                        "itemId": "Item4",
                                        "name": "ItemName02",
                                        "description": "Description",
                                        "url": "http://XXXXX.jpg",
                                        "tinyUrl": "http://tinyurl.com/berc7dr",
										"price": 20
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        }
    }
}
-(App42Response*)getItemsCountByCategory:(NSString*)catalogueName categoryName:(NSString*)categoryName

Fetches count of all items for a Catalogue and Category

Parameters:

catalogueName - Name of the Catalogue from which count of item has to be fetched
categoryName - Name of the Category from which count of item has to be fetched

Returns:

App42Response object

Response: App42Response Object

For more details click Exception
NSString *catalogueName = @"CatalogueName01";
NSString *categoryName = @"CategoryName01";						

App42Response *response = [catalogueServiceObject getItemsCountByCategory:catalogueName categoryName:categoryName] /* returns the App42Response objects. */
BOOL success = response.isResponseSuccess;
int totalRecords= response.totalRecords;
NSString *jsonResponse = [response toString]; /* returns the response in JSON format. (as shown below)*/   
{
    "app42": {
        "response": {
            "success": true,
            "totalRecords": 3
        }
    }
}
-(Catalogue*)getItemsByCategory:(NSString*)catalogueName categoryName:(NSString*)categoryName max:(int)max offset:(int)offset

Fetches all items for a Catalogue and Category by paging.

Parameters:

catalogueName - Name of the Catalogue from which item has to be fetched
categoryName - Name of the Category from which item has to be fetched
max - Maximum number of records to be fetched
offset - From where the records are to be fetched

Returns:

Catalogue object

Response: Catalogue Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
3403 - NOT FOUND - Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' does not exist.
3407 - NOT FOUND - The number of items for category by the name '<categoryName>' for Catalogue by the name '<catalogueName>' are less than the specified offset : <offset>.
*/ 		       
For more details click Exception
NSString *catalogueName = @"catalogueName12341338890353836";
NSString *categoryName = @"categoryName21341338890353836";
int max = 1;
int offset = 0;
						
Catalogue *catalogue = [catalogueService getItemsByCategory:catalogueName categoryName:categoryName max:max offset:offset]; /* returns the Catalogue object. */ 
NSLog(@"catalogueName =  %@",catalogue.name); 
NSMutableArray *categoryList = catalogue.categoryListArray;
for(CategoryData *category in categoryList)
{
	NSLog(@"name is = %@",category.name);
	NSLog(@"description is = %@",category.description);
	NSMutableArray *itemList = category.itemListArray;
	for (categoryItem *item in itemList)
	{
		NSLog(@"price is = %f",item.price);
		NSLog(@"itemId is = %@",item.itemId);
		NSLog(@"name is = %@",item.name);
	}  
}
String jsonResponse = catalogue.toString(); /* returns the response in JSON format. (as shown below)*/   
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "categories": {
                        "category": {
                            "name": "CategoryName01",
                            "items": {
                                "item": {
                                    "itemId": "iiiiiiiii",
                                    "name": "Item",
                                    "description": "Description 1",
                                    "url": "http://XXXXX.jpg",
                                    "tinyUrl": "http://tinyurl.com/cpfy7zj",
                                    "price": 20
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
-(Catalogue*)getItemById:(NSString*)catalogueName categoryName:(NSString*)categoryName itemId:(NSString*)itemId

Fetches Item by id for a Catalogue and Category.

Parameters:

catalogueName - Name of the catalogue
categoryNmae - Name of the category
itemId - item id for which information has to be fetched

Returns:

Item whose id is provided

Response: Catalogue Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
3403 - NOT FOUND - Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' does not exist.
3405 - NOT FOUND - Item with the id '<itemId>' for the Category by the name '<categoryName>' and Catalogue by the name '<catalogueName>' does not exist.
*/ 		      
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
NSString *categoryName = @"CategoryName01";
NSString *itemId = @"ItemId01";
						
Catalogue *catalogue = [catalogueService getItemById:catalogueName categoryName:categoryName itemId:itemId]; /* returns the Catalogue object. */ 
NSLog(@"catalogueName =  %@",catalogue.name); 
NSMutableArray *categoryList = catalogue.categoryListArray;
for(CategoryData *category in categoryList)
{
	NSLog(@"name is = %@",category.name);
	NSLog(@"description is = %@",category.description);
	NSMutableArray *itemList = category.itemListArray;
	for (categoryItem *item in itemList)
	{
		NSLog(@"price is = %f",item.price);
		NSLog(@"itemId is = %@",item.itemId);
		NSLog(@"name is = %@",item.name);
	}  
}NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. */  (as shown below)*/
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "categories": {
                        "category": {
                            "name": "CategoryName01",
                            "items": {
                                "item": {
                                    "itemId": "ItemId01",
                                    "name": "ItemName01",
                                    "description": "ItemDescription01",
                                    "url": "http://XXXXX.jpg",
                                    "tinyUrl": "http://tinyurl.com/cun46z4",
                                    "price": 200
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
-(App42Response*)removeAllItems:(NSString*)catalogueName

Removes all Items in a Catalogue.

Parameters:

catalogueName - Name of the Catalogue from which item has to be removed

Returns:

The removed Items

Returns:

App42Response if removed successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
*/ 	       
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
App42Response *response = [catalogueService removeAllItems:catalogueName]; /* returns the Catalogue object. */ 
BOOL success = reponse.isResponseSuccess;
NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. */  (as shown below)*/
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "description": "CatalogueName"
                }
            }
        }
    }
}
-(App42Response*)removeItemsByCategory:(NSString*)catalogueName categoryName:(NSString*)categoryName

Removes all Items from a Catalogue and Category.

Parameters:

catalogueName - Name of the Catalogue from which item has to be removed
categoryName - Name of the Category from which item has to be removed

Returns:

The removed Items

Response: App42Response Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
3403 - NOT FOUND - Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' does not exist.
*/ 	        
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
NSString *categoryName = @"CategoryName01";		
App42Response *response = [catalogueService removeItemsByCategory:catalogueName categoryName:categoryName]; /* returns the Catalogue object. */ 
BOOL success = reponse.isResponseSuccess;
NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. */  (as shown below)*/
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "categories": {
                        "category": {
                            "name": "CategoryName01",
                            "items": {
                                "item": {
                                    "itemId": "Item4",
                                    "name": "ItemName02",
                                    "description": "Description",
                                    "url": "http://XXXXX.jpg",
                                    "tinyUrl": "http://tinyurl.com/cwzuxpc",
                                    "price": 20
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
-(App42Response*)removeItemById:(NSString*)catalogueName categoryName:(NSString*)categoryName itemId:(NSString*)itemId

Removes Item by Id.

Parameters:

catalogueName - Name of the Catalogue from which item has to be removed
categoryName - Name of the Category from which item has to be removed
itemID - Item id which has to be removed

Returns:

The removed Items

Response: App42Response Object

Exception:

This method throws following exception.
/*
3401 - NOT FOUND - Catalogue by the name '<catalogueName>' does not exist.
3403 - NOT FOUND - Category by the name '<categoryName>' for the Catalogue by the name '<catalogueName>' does not exist.
3406 - NOT FOUND - Item with the id '<itemId>' does not exist.
*/ 		       
For more details click Exception
NSString *catalogueName = @"CatalogueName01";
NSString *categoryName = @"CategoryName01";
NSString *itemId =	@"ItemId01";	
App42Response *response = [catalogueService removeItemById:catalogueName categoryName:categoryName itemId:itemId]; /* returns the Catalogue object. */ 
BOOL success =  response.isResponseSuccess;  
NSString *jsonResponse = [catalogue toString]; /* returns the response in JSON format. */  (as shown below)*/
{
    "app42": {
        "response": {
            "success": true,
            "catalogues": {
                "catalogue": {
                    "name": "CatalogueName01",
                    "categories": {
                        "category": {
                            "name": "CategoryName01",
                            "items": {
                                "item": {
                                    "itemId": "ItemId01",
                                    "name": "ItemName01",
                                    "description": "ItemDescription01",
                                    "url": "http://XXXXX.jpg",
                                    "tinyUrl": "http://tinyurl.com/c3gd7om",
                                    "price": 200
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}