App42 Cloud API

Windows Phone Cloud SDK

Review/Rating

The service is a Review & Rating manager for any item. The item can be anything which has an id e.g. App on a AppStore/Marketplace, items in a catalogue, articles, blogs etc. It manages the comments and its associated rating. It also provides methods to fetch average, highest etc. reviews. Reviews can be also be muted or unmuted if it has any objectionable content.

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 api = new ServiceAPI("<API_KEY>","<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 ReviewService, BuildReviewService() method needs to be called.

ReviewService reviewService = api.BuildReviewService();

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

The Windows Phone API's work in an asynchronous mode that means the response will not be available immediately and all the API methods would not return any value and have return type as void. The response will be returned in callback methods which the caller will provide to the calling method.
As mentioned above that the response will be returned in callback methods, every API method is taking instance of App42Callback (as the last parameter) which will have the implementation of 2 methods: OnSuccess & OnException.(as shown below)

	public class CallBack : App42Callback
	{
		public override void OnSuccess(Object obj)
		{
			Review review = (Review) obj;
			//Do whatever you want with the user object
		}
		public override void OnException(App42Exception e)
		{
			//Do whatever you want with the exception
		}
	}
                            

The callback methods will return the response in the form of Object which will have to be type cast to the object domain object (e.g. App42Response / Review / IList in this case) The Domain object 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.

public override void OnSuccess(Object obj)
{
Review review = (Review) obj; 
String userId =  review.GetUserId();  
String itemId =  review.GetItemId(); 
String comment =  review.GetComment(); 
String rating =  review.GetRating(); 
String jsonResponse = review.ToString(); /* returns the response in JSON format. */
}
                            

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

E.g. If App developer is requesting for a Review for the item Id which is not in database, the function will throw the App42Exception (as shown below) with message as "Not Found" and the appErrorCode as "3100" and the details as "Reviews for the Item with Id '<itemId>' do not exist".

		public override void OnException(App42Exception ex)
		{
			int appErrorCode = ex.GetAppErrorCode();
			int httpErrorCode = ex.GetHttpErrorCode();
			
			String jsonText = ex.GetMessage(); /* returns the Exception text in JSON format. (as shown below)*/	
		}
                            
	{
		"app42Fault": {
			"httpErrorCode": 404,
			"appErrorCode": 3100,
			"message": "Not Found",
			"details": "Reviews for the Item Id  'itemId'  does not Exists"
		}
	}							

Below are the HTTP Error Codes and their description, the function under the Review/Rating 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 Review/Rating API can throw.

/*
3100 - NOT FOUND - Reviews for the Item with Id '<itemId>' do not exist. 
3101 - NOT FOUND - Review with the Id '<reviewId>' does not exist. 
3102 - BAD REQUEST - Reviews for the User with Id '<userId>' and Item with Id '<itemId>' already exists.
3103 - NOT FOUND - Reviews do not exist.
3104 - NOT FOUND - The number of reviews are less than the specified offset : '<offset>'.
3105 - NOT FOUND - The number of reviews for the Item with Id '<itemId>' are less than the specified offset : '<offset>'.
*/				

Various functions available under Review/Rating API has been explained below.

public void CreateReview(String userID, String itemID, String reviewComment, Double reviewRating, App42Callback requestCallback)

Creates review for the specified item on the cloud.

Parameters:

userID - The user who has created the review
itemID - The item for which the review has to be created
reviewComment - The review comment
reviewRating - Review rating in Double
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Review object containing the review which has been created

Response: Review Object

Exception:

This method throws following exception.
/*
3102 - BAD REQUEST - Reviews for the User with Id '<userId>' and Item with Id '<itemId>' already exists.
*/ 	        
For more details click Exception
String userID = "Nick";
String itemID = "itemID";
String reviewComment = "reviewComment";
double reviewRating = 3;

reviewService.CreateReview(userID,itemID,reviewComment,reviewRating,requestCallback); /* returns the Review object. */ 
OnSuccess(Object obj){
Review review = (Review) obj;
Console.WriteLine("userId is " + review.GetUserId());
Console.WriteLine("itemId is " + review.GetItemId());
Console.WriteLine("comment is " + review.GetComment());
Console.WriteLine("rating is " + review.GetRating());
String jsonResponse = review.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": {
                    "userId": "Nick",
                    "itemId": "itemID",
                    "reviewId": "84faa1fe-f67d-47a5-8849-df61e96bf3eb",
                    "comment": "reviewComment",
                    "rating": 3,
                    "createdOn": "2012-05-08T13:21:10.266Z"
                }
            }
        }
    }
}
public void GetAllReviews(App42Callback requestCallback)

Fetches all reviews for the App.

Parameters:

requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

IList of Review object containing all the reviews for the App

Response: IList<Review> Object

Exception:

This method throws following exception.
/*
3103 - NOT FOUND - Reviews do not exist.
*/ 		       
For more details click Exception
reviewService.GetAllReviews(requestCallback); /* returns the list of Review object. */ 
OnSuccess(Object obj){
IList<Review> reviewList = (IList<Review>) obj;
for(int i = 0; i <reviewList.Count; i++)
{
Console.WriteLine("userId is " + review.GetUserId());
Console.WriteLine("itemId is " + review.GetItemId());
Console.WriteLine("comment is " + review.GetComment());
Console.WriteLine("rating is " + review.GetRating());
}
String jsonResponse = reviewList.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": [
                    {
                        "userId": "Nick",
                        "itemId": "itemID",
                        "reviewId": "84faa1fe-f67d-47a5-8849-df61e96bf3eb",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 3,
                        "createdOn": "2012-05-08T13:21:10.000Z"
                    },
                    {
                        "userId": "BOB",
                        "itemId": "itemIDs",
                        "reviewId": "c657fe7d-bce4-4585-afe1-4eb18c557a28",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 3,
                        "createdOn": "2012-05-08T13:22:11.000Z"
                    },
                    {
                        "userId": "Nick",
                        "itemId": "itemIDs",
                        "reviewId": "e371aefa-0753-43df-a18c-fa8850ce3b96",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 3,
                        "createdOn": "2012-05-08T13:22:50.000Z"
                    },
                    {
                        "userId": "Nick",
                        "itemId": "itemID",
                        "reviewId": "2d2753f1-cdb7-454b-8a52-ac6a163515fa",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 3,
                        "createdOn": "2012-05-08T13:23:24.000Z"
                    },
                    {
                        "userId": "Jill",
                        "itemId": "ItemID",
                        "reviewId": "037d06f9-f2c2-43dd-887f-d5ba2101a981",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 5,
                        "createdOn": "2012-05-08T13:24:19.000Z"
                    }
                ]
            }
        }
    }
}
public void GetAllReviewsCount(App42Callback requestCallback)

Fetches count of all reviews for the App.

Parameters:

requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response containing count of all the reviews for the App

Response: App42Response Object

Exception:

This method throws following exception.
/*
3103 - NOT FOUND - Reviews do not exist.
*/ 	        
For more details click Exception
reviewService.GetAllReviewsCount(requestCallback); /* returns the App42Response  object. */ 
OnSuccess(Object obj)
{
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
int totalRecords = response.GetTotalRecords();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "totalRecords": 3
        }
    }
}
public void GetAllReviews(int max, int offset, App42Callback requestCallback)

Fetches all reviews for the App by Paging.

Parameters:

max - Maximum number of records to be fetched
offset - From where the records are to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

List of Review object containing all the reviews for the App

Response: IList<Review> Object

Exception:

This method throws following exception.
/*
3104 - NOT FOUND - The number of reviews are less than the specified offset : <offset>.
*/ 		        
For more details click Exception
int max = 1;
int offset = 0;

reviewService.GetAllReviews(max,offset,requestCallback); /* returns the list of Review object. */ 
OnSuccess(Object obj){
IList<Review> reviewList = (IList<Review>) obj;
for(int i = 0; i <reviewList.Count; i++)
	{
		Console.WriteLine("userId is " + reviewList[i].GetUserId());
		Console.WriteLine("itemId is " + reviewList[i].GetItemId());
		Console.WriteLine("comment is " + reviewList[i].GetComment());
		Console.WriteLine("rating is " + reviewList[i].GetRating());
	}
String jsonResponse = reviewList.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": [
                    {
                        "userId": "Nick",
                        "itemId": "ItemID",
                        "reviewId": "f3c93a6f-c784-4108-83a9-76163c1ae2c6",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 5,
                        "createdOn": "2012-06-02T13:24:36.000Z"
                    },
                    {
                        "userId": "BOB",
                        "itemId": "ItemID",
                        "reviewId": "3fee9765-d0e9-49fb-a109-8d705e343a3b",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 5,
                        "createdOn": "2012-06-02T13:24:40.000Z"
                    }
                ]
            }
        }
    }
}
public void GetReviewByItem(String itemId, App42Callback requestCallback)

Fetches All Reviews based on the itemId.

Parameters:

itemId - The item for which reviews have to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

IList of Review object containing all the reviews for a item

Response: IList<Review> Object

Exception:

This method throws following exception.
/*
3100 - NOT FOUND - Reviews for the Item with Id '<itemId>' do not exist.
*/ 		       
For more details click Exception
String itemId = "itemID";
						
reviewService.GetReviewsByItem(itemId,requestCallback); /* returns the list of Review object. */ 
OnSuccess(Object obj){
IList<Review> reviewList = (IList<Review>) obj;
for(int i = 0; i <reviewList.Count; i++)
	{
		Console.WriteLine("userId is " + reviewList[i].GetUserId());
		Console.WriteLine("itemId is " + reviewList[i].GetItemId());
		Console.WriteLine("comment is " + reviewList[i].GetComment());
		Console.WriteLine("rating is " + reviewList[i].GetRating());
	}
String jsonResponse = reviewList.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": [
                    {
                        "userId": "Nick",
                        "itemId": "itemID",
                        "reviewId": "84faa1fe-f67d-47a5-8849-df61e96bf3eb",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 3,
                        "createdOn": "2012-05-08T13:21:10.000Z"
                    },
                    {
                        "userId": "BOB",
                        "itemId": "itemID",
                        "reviewId": "2d2753f1-cdb7-454b-8a52-ac6a163515fa",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 3,
                        "createdOn": "2012-05-08T13:23:24.000Z"
                    },
                    {
                        "userId": "Alquert",
                        "itemId": "ItemID",
                        "reviewId": "037d06f9-f2c2-43dd-887f-d5ba2101a981",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 5,
                        "createdOn": "2012-05-08T13:24:19.000Z"
                    },
                    {
                        "userId": "Alquert",
                        "itemId": "itemID",
                        "reviewId": "a6072c3d-5003-44cf-92ff-264c3f424b3b",
                        "status": "UNMUTED",
                        "comment": "reviewComment",
                        "rating": 4,
                        "createdOn": "2012-05-08T13:26:40.000Z"
                    }
                ]
            }
        }
    }
}
public void GetReviewCountByItem(String itemId, int max, int offset, App42Callback requestCallback)

Fetches count of All Reviews based on the itemId

Parameters:

itemId - The item for which count of reviews have to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response containing count of all the reviews for a item

Response: App42Response Object

Exception:

This method throws following exception.
/*
3100 - NOT FOUND - Reviews for the Item with Id '<itemId>' do not exist. 
*/ 		       
For more details click Exception
String itemId = "ItemID";

reviewService.GetReviewCountByItem(itemId,max,offset,requestCallback); /* returns the App42Response  object. */ 
OnSuccess(Object obj){
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
int totalRecords = response.GetTotalRecords();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "totalRecords": 3
        }
    }
}
public void GetReviewByItem(String itemId,int max, int offset, App42Callback requestCallback)

Fetches All Reviews based on the itemId by paging.

Parameters:

itemId - The item for which reviews have to be fetched
max - Maximum number of records to be fetched
offset - From where the records are to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

IList of Review object containing all the reviews for a item

Response: IList<Review> Object

Exception:

This method throws following exception.
/*
3105 - NOT FOUND - The number of reviews for the Item with Id '<itemId>' are less than the specified offset : <offset>.
*/ 		        
For more details click Exception
String itemId = "ItemID";
int max = 1;	
int offset = 0;

reviewService.GetReviewsByItem(max,offset,requestCallback); /* returns the list of Review object. */ 
OnSuccess(Object obj){
IList<Review> reviewList = (IList<Review>) obj;
for(int i = 0; i <reviewList.Count; i++)
	{
		Console.WriteLine("userId is " + reviewList[i].GetUserId());
		Console.WriteLine("itemId is " + reviewList[i].GetItemId());
		Console.WriteLine("comment is " + reviewList[i].GetComment());
		Console.WriteLine("rating is " + reviewList[i].GetRating());
	}
String jsonResponse = reviewList.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": {
                    "userId": "Nick",
                    "itemId": "ItemID",
                    "reviewId": "54828228-b629-49b6-860c-b9c12021a52f",
                    "status": "UNMUTED",
                    "comment": "reviewComment",
                    "rating": 5,
                    "createdOn": "2012-06-02T13:23:03.000Z"
                }
            }
        }
    }
}
public void GetAverageReviewByItem(String itemId, App42Callback requestCallback)

Fetches the average review for the specified itemId.

Parameters:

itemId - The item for which reviews have to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Review object containing the average review for a item

Response: Review Object

Exception:

This method throws following exception.
/*
3100 - NOT FOUND - Reviews for the Item with Id '<itemId>' do not exist.
*/ 	        
For more details click Exception
String itemId = "itemID";
						
reviewService.GetAverageReviewByItem(itemId,requestCallback); /* returns the Review object. */ 
OnSuccess(Object obj){
Review review = (Review) obj;
Console.WriteLine("userId is " + review.GetUserId());
Console.WriteLine("rating is " + review.GetRating());
String jsonResponse = review.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": {
                    "itemId": "itemID",
                    "rating": 4.108108
                }
            }
        }
    }
}
public void GetHighestReviewByItem(String itemId, App42Callback requestCallback)

Fetches the highest review for the specified itemId.

Parameters:

itemId - The item for which the highest review has to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Review object containing the highest review for a item

Response: Review Object

Exception:

This method throws following exception.
/*
3100 - NOT FOUND - Reviews for the Item with Id '<itemId>' do not exist.
*/ 		        
For more details click Exception
String itemId = "itemID";
						
reviewService.GetHighestReviewByItem(itemId,requestCallback); /* returns the Review object. */ 
OnSuccess(Object obj){
Review review = (Review) obj;
Console.WriteLine("userId is " + review.GetUserId());
Console.WriteLine("rating is " + review.GetRating());
String jsonResponse = review.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": {
                    "itemId": "itemID",
                    "rating": 5
                }
            }
        }
    }
}
public void GetLowestReviewByItem(String itemId, App42Callback requestCallback)

Fetches the lowest review for the specified itemId.

Parameters:

itemId - The item for which the lowest review has to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Review object containing the lowest review for a item

Response: Review Object

Exception:

This method throws following exception.
/*
3100 - NOT FOUND - Reviews for the Item with Id '<itemId>' do not exist.
*/ 		        
For more details click Exception
String itemId = "itemID";
						
reviewService.GetLowestReviewByItem(itemId,requestCallback); /* returns the Review object. */ 
OnSuccess(Object obj){
IList<Review> reviewList = (IList<Review>) obj;
for(int i = 0; i <reviewList.Count; i++)
	{
		Console.WriteLine("userId is " + reviewList[i].GetUserId());
		Console.WriteLine("rating is " + reviewList[i].GetRating());
	}
String jsonResponse = reviewList[i].ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": {
                    "itemId": "itemID",
                    "rating": 3
                }
            }
        }
    }
}
public void Mute(String reviewId, App42Callback requestCallback)

Mutes the specified reviewList[i].

Parameters:

reviewId - The Id of the review which has to be muted
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response if muted successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
3101 - NOT FOUND - Review with the Id '<reviewId>' does not exist.
*/ 		        
For more details click Exception
String reviewId = "430cc684-de35-4595-aa38-23c99bda18fc";
						
reviewService.Mute(reviewId,requestCallback); /* returns the App42Response object. */
OnSuccess(Object obj){
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": {
                    "reviewId": "430cc684-de35-4595-aa38-23c99bda18fc"
                }
            }
        }
    }
}
public void Unmute(String reviewId, App42Callback requestCallback)

UnMutes the specified reviewList[i].

Parameters:

reviewId - The Id of the review which has to be unmuted
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response if unmuted successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
3101 - NOT FOUND - Review with the Id '<reviewId>' does not exist.
*/ 		       
For more details click Exception
String reviewId = "430cc684-de35-4595-aa38-23c99bda18fc";
						
reviewService.Unmute(reviewId,requestCallback); /* returns the App42Response object. */
OnSuccess(Object obj){
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "reviews": {
                "review": {
                    "reviewId": "430cc684-de35-4595-aa38-23c99bda18fc"
                }
            }
        }
    }
}