//
//  DOHTTPResponseParser.h
//  DOCore
//
//  Created by Ben Dolman on 3/3/15.
//
//

#import <Foundation/Foundation.h>

@class DOHTTPRoute;

/**
 * A class to assist in the consolidation of HTTP response parsing and error handling.
 *  1. Create an instance of the parser
 *  2. Register routes that correspond to REST calls on the server. Associate that route
 *     with a pipeline of custom filters (error handling, JSON deserialization, etc.)
 *  3. Parse a response from the server. You'll either get back a parsed object that has gone
 *     successfully through the filter pipeline, or you'll get an error.
 */
@interface DOHTTPResponseParser : NSObject

/** 
 * Associates a route with a pipeline of response filters. When parsing a response the
 * parser will filter the response object and data through each of these filters, in sequence.
 * @note Each response must match exactly one route.
 *
 * @param route The route
 * @param filters An array of objects that conform to the DOHTTPResponseFilter protocol.
 */
- (void)registerRoute:(DOHTTPRoute *)route pipeline:(NSArray *)filters;

/**
 * Parses the response by finding matching route and running the data through the associated
 * filter pipeline. You'll either get back a fully filtered object or nil+error.
 *
 * @param response The response to parse
 * @param data The response data to pass to the first item in the filter pipeline.
 * @param request The original request (must have URL and HTTPMethod set)
 * @param error Error pointer that will be set by filters if they encounter an error.
 */
- (id)parseResponse:(NSHTTPURLResponse *)response
       responseData:(NSData *)data
         forRequest:(NSURLRequest *)request
              error:(NSError **)error;

@end
