API.Requests.cs

Go to the documentation of this file.

using System;
using System.Collections;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Linq;
using System.Net;
using System.Net.Sockets;
 
using AnalyzeRe.APITypes;
using AnalyzeRe.Authentication;
using AnalyzeRe.Rest;
using AnalyzeRe.Utilities;
using RestSharp;
 
namespace AnalyzeRe
{
    public static partial class API
    {
#if DEBUG
        public static volatile bool RequestLogging = true;
#endif
        #region OPTIONS
        public static OptionsResponse Options(
            IEnumerable<Parameter> requestParameters = null, int? timeout = null)
        {
            return RequestAndParse<OptionsResponse>("/", Method.OPTIONS,
                new RequestParameters(requestParameters), timeout);
        }
        #endregion OPTIONS
 
        #region Explicit Get Methods
        public static T Get<T>(
            string id,
            IEnumerable<Parameter> requestParameters = null,
            int? timeout = null) where T : IAPIResource
        {
            ValidateResourceId(id);
            string collectionName = GetCollectionName<T>();
            return RequestAndParse<T>($"{collectionName}/{id}", Method.GET, requestParameters, timeout);
        }
 
        public static IAPIResource Get(Type resourceType,
            string id,
            IEnumerable<Parameter> requestParameters = null,
            int? timeout = null)
        {
            ValidateResourceId(id);
            string collectionName = GetCollectionName(resourceType);
            return (IAPIResource)RequestAndParse(resourceType, $"{collectionName}/{id}", Method.GET, requestParameters, timeout);
        }
 
        // TODO: This isn't well tested yet (what if we pass a path with a different base URL?)
        public static T GetUri<T>(
            Uri href,
            IEnumerable<Parameter> requestParameters = null,
            int? timeout = null)
        {
            // TODO: What if the URL contains query parameters?
            // How do we merge with GetOrPost requestParameters?
            return RequestAndParse<T>(href.PathAndQuery, Method.GET, requestParameters, timeout);
        }
 
        public static object GetUri(Type deserializeType,
            Uri href,
            IEnumerable<Parameter> requestParameters = null,
            int? timeout = null)
        {
            return RequestAndParse(deserializeType, href.PathAndQuery, Method.GET,
                requestParameters, timeout);
        }
        #endregion Explicit Get Methods
 
        #region GET Resource Collection
        public static ICollectionResponse<T> GetResourceList<T>(
            IEnumerable<Parameter> requestParameters = null,
            string collectionNameOverride = null,
            int? timeout = null)
            where T : IAPIResource
        {
            string collectionName = DetermineCollectionNameAndBaseType(typeof(T),
                collectionNameOverride, out Type baseType);
 
            if (timeout == null)
                timeout = DefaultRequestTimeoutCollections;
            if (typeof(T) == baseType)
                return RequestAndParse<CollectionResponse<T>>(collectionName,
                    Method.GET, requestParameters, timeout);
            // If we have requested a list of some derived type, we must
            // determine the run-time list type to query.
            return (ICollectionResponse<T>)GetDerivedResourceList(typeof(T),
                requestParameters, timeout.Value, collectionName, baseType);
        }
 
        public static ICollectionResponse<IAPIResource> GetResourceList(
            Type resourceType,
            IEnumerable<Parameter> requestParameters = null,
            string collectionNameOverride = null,
            int? timeout = null)
        {
            string collectionName = DetermineCollectionNameAndBaseType(
                resourceType, collectionNameOverride, out Type baseType);
            return GetDerivedResourceList(resourceType, requestParameters,
                timeout ?? DefaultRequestTimeoutCollections, collectionName, baseType);
        }
 
        #region Private Helper Methods
        // Challenge - type constraints allow this method to be called with types derived from the
        // base type, but when the results come back (for instance for
        // `getResourceListGenericHelper{CatXL}()`), the deserializer needs to be able to
        // parse the json as a List of Layers, not a List of CatXL, so we need to actually
        // discover the base type that defines the collection endpoint at which the objects
        // can be retrieved. Calling a generic method with a type parameter determined at run-time
        // requires the ugly reflection at the end of this implementation. This wouldn't be a
        // problem if the deserializer type parameter was passed in as a run-time type (like the
        // Microsoft serialization class) rather than a compile time generic method type parameter.
        // TODO: These reflection operations can benefit from caching.
        private static ICollectionResponse<IAPIResource> GetDerivedResourceList(
            Type resourceType,
            IEnumerable<Parameter> requestParameters,
            int timeout,
            string collectionName,
            Type baseType)
        {
            if (resourceType != baseType)
            {
                // Try to determine a base resource type or interface that we can use to hold a
                // list of server results.
                if (baseType.ContainsGenericParameters) // TODO: Support something more elaborate
                {
                    // This is a problem, we can't just instantiate something without generic
                    // arguments. We can attempt to fill them in from the constraints.
                    if (!baseType.IsInterface)
                    {
                        // This is a problem. We are about instantiate a sub-type with generic
                        // arguments. Even if these arguments are covariantly valid, this class
                        // can't be (because it's not an interface), so we won't be able to add
                        // elements to the list we're about to make, as covariance has to be
                        // supported all the way to the last generic argument to be able to store
                        // derived list elements. The solution is to guess at an interface
                        // implemented by this baseType that IS covariant. */
 
                        // Get any interfaces that have generic parameters
                        // TODO: can we do better than this guess?
                        IEnumerable<Type> baseInterfaces = baseType.GetInterfaces()
                            .Where(i => i.ContainsGenericParameters);
                        // Pick the last applied interface with generic parameters.
                        baseType = baseInterfaces.Last().GetGenericTypeDefinition();
                    }
                    // Assuming there's only one generic argument, and assuming that its first
                    // generic parameter constraint is a covariantly valid interface parameter and
                    // matches the type the we got this interface from, this might work.
                    baseType = baseType.MakeGenericTypeFast(
                        baseType.GetGenericArguments()[0].GetGenericParameterConstraints()[0]);
                    // If we're lucky we now have an covariant base interface type for which
                    // elements of type T can be assigned.
                }
            }
 
            // TODO: Server behaviour is not consistent / well enough defined yet to use its
            //       type searching in an automated way.
            /*/ Create the query parameter that (once supported by the server) will filter by type.
            Parameter typeSearchParameter = new Parameter
            {
                Type = ParameterType.GetOrPost,
                Name = "type",
                Value = TypeResolver.GetTypeNameForAPIType(resourceType)
            };
            requestParameters = (requestParameters ?? new Parameter[] { })
                .Concat(new[] { typeSearchParameter });
            */
 
            // Execute the query on the server
            IRestResponse queryResponse = ExecuteRestRequest(collectionName, Method.GET,
                requestParameters, timeout);
            // Parse the server response into a list of the base type
            Type listOfBaseType = typeof(CollectionResponse<>).MakeGenericTypeFast(baseType);
            ICollectionResponse<IAPIResource> result = (ICollectionResponse<IAPIResource>)
                ExtractRestResponse(queryResponse, listOfBaseType);
 
            // Filter result list to only items of type resourceType (which derive from baseType)
            Type listOfResourceTypeType =
                typeof(CollectionResponse<>).MakeGenericTypeFast(resourceType);
            object targetTypeResult = Activator.CreateInstance(listOfResourceTypeType);
            IList filteredResults = (IList)
                Activator.CreateInstance(typeof(List<>).MakeGenericTypeFast(resourceType));
 
            // HACK: To support sub-type-specific searches (which currently isn't supported server
            // side, we filter results to the specified type.
            // TODO: It doesn't make much sense to include meta if we are cutting down the results
            // to a specific derived type.
            listOfResourceTypeType.GetProperty(nameof(result.meta))
                .SetValue(targetTypeResult, result.meta, null);
            foreach (IAPIResource item in result.items.Where(resourceType.IsInstanceOfType))
            {
                filteredResults.Add(item);
            }
            listOfResourceTypeType.GetProperty(nameof(result.items))
                .SetValue(targetTypeResult, filteredResults, null);
 
            return (ICollectionResponse<IAPIResource>)targetTypeResult;
        }
 
        // Helper method to resolve the resource collection name and the type that defined it.
        private static string DetermineCollectionNameAndBaseType(
            Type resourceType, string collectionNameOverride, out Type baseType)
        {
            baseType = resourceType;
            string collectionName;
            try
            {
                collectionName = collectionNameOverride ??
                    GetCollectionName(resourceType, out baseType);
            }
            catch (Exception e)
            {
                throw new ArgumentException(
                    "Could not resolve the collection name for this Resource, it must be " +
                    "provided manually via the 'collectionName' optional parameter.", e);
            }
            // If the defining type is generic, it is necessary to produce a
            // covariant type which we can use to as a generic type
            // parameter to an instantiable class wrapping this type.
            if (baseType.IsGenericType)
                baseType = TypeResolver.GetGenericCovariantBase(baseType);
            return collectionName;
        }
        #endregion Private Helper Methods
        #endregion GET Resource Collection
 
        #region Search Resource Collection
        public enum SearchType
        {
            Basic,
            Advanced
        };
 
        public static ICollectionResponse<T> SearchResourceList<T>(
            string searchTerms,
            IEnumerable<Parameter> requestParameters = null,
            string collectionNameOverride = null,
            int? timeout = null,
            SearchType searchType = SearchType.Basic)
            where T : IAPIResource
        {
            requestParameters = searchType == SearchType.Basic ?
                Parameters.Search(searchTerms).AddParameters(requestParameters) :
                Parameters.AdvancedSearch(searchTerms).AddParameters(requestParameters);
            return GetResourceList<T>(requestParameters, collectionNameOverride, timeout);
        }
 
        public static ICollectionResponse<IAPIResource> SearchResourceList(
            Type resourceType,
            string searchTerms,
            IEnumerable<Parameter> requestParameters = null,
            string collectionNameOverride = null,
            int? timeout = null,
            SearchType searchType = SearchType.Basic)
        {
            requestParameters = searchType == SearchType.Basic ?
                Parameters.Search(searchTerms).AddParameters(requestParameters) :
                Parameters.AdvancedSearch(searchTerms).AddParameters(requestParameters);
            return GetResourceList(resourceType, requestParameters, collectionNameOverride, timeout);
        }
        #endregion Search Resource Collection
 
        #region Batch Requests
        public static ICollectionResponse<T> BatchGet<T>(
            IEnumerable<string> ids,
            IEnumerable<Parameter> requestParameters = null,
            string collectionNameOverride = null,
            int? timeout = null)
            where T : IAPIResource
        {
            return GetResourceList<T>(Parameters.Ids(ids)
                    .AddParameters(Parameters.Page(0, ids.Count()))
                    .AddParameters(requestParameters),
                collectionNameOverride, timeout);
        }
 
        public static ICollectionResponse<IAPIResource> BatchGet(
            Type resourceType,
            IEnumerable<string> ids,
            IEnumerable<Parameter> requestParameters = null,
            string collectionNameOverride = null,
            int? timeout = null)
        {
            return GetResourceList(resourceType, Parameters.Ids(ids)
                    .AddParameters(Parameters.Page(0, ids.Count()))
                    .AddParameters(requestParameters),
                collectionNameOverride, timeout);
        }
        #endregion Batch Requests
 
        #region Combined Request and Deserialization
        public static T RequestAndParse<T>(
            string resource,
            Method method,
            IEnumerable<Parameter> requestParameters = null,
            int? timeout = null)
        {
            IRestResponse response = ExecuteRestRequest(resource, method, requestParameters, timeout);
            return ExtractRestResponse<T>(response);
        }
 
        public static object RequestAndParse(
            Type deserializeType,
            string resource,
            Method method,
            IEnumerable<Parameter> requestParameters = null,
            int? timeout = null)
        {
            IRestResponse response = ExecuteRestRequest(resource, method, requestParameters, timeout);
            return ExtractRestResponse(response, deserializeType);
        }
        #endregion Combined Request and Deserialization
 
        #region Basic REST Request
        public static IRestResponse ExecuteRestRequest(
            string resource,
            Method method,
            IEnumerable<Parameter> requestParameters = null,
            int? timeout = null,
            bool returnRawResponse = false,
            Action<Stream> responseStreamReader = null)
        {
            int attempts = 1;
            IRestResponse response;
            DateTime? requestStartTime = null;
            do
            {
 
                RestRequest request = new RestRequest(resource, method);
                // Add parameters (Cookies, HttpHeaders, GetOrPost Parameters, RequestBody...)
                PrepareRequestParameters(ref request, requestParameters);
                request.Timeout = timeout ?? DefaultRequestTimeout;
 
                // If the desired timeout exceeds the default ReadWriteTimeout (5 minutes),
                // increase it as well.
                if (request.Timeout > 300000)
                    request.ReadWriteTimeout = request.Timeout;
                
                // Set up the Stream reader if applicable
                if (responseStreamReader != null)
                    request.ResponseWriter = responseStreamReader;
 
                // Execute the request
                IRestClient client = GetRestClient();
                if(requestStartTime == null)
                    requestStartTime = DateTime.UtcNow;
                response = ExecuteRequest(client, request);
 
                // If configured not to check for HTTP status errors, return the response directly.
                if (returnRawResponse)
                    return response;
 
                // If this gets set to true, the request may be retried
                bool should_retry = false;
 
                // Determine whether we've been issued a redirect request.
                string redirection = CheckForRedirect(response, client);
                // Change the resource to the new location's relative path
                if (redirection != null)
                {
                    resource = redirection;
                    should_retry = true;
                }
 
                // Returns TRUE if a temporary error was encountered and the request should be retried.
                // Returns FALSE if the request completed successfully.
                // Raises a meaningful exception if a permanent failure occurred.
                should_retry = should_retry || 
                    CheckIncompleteResponse(response, requestStartTime.Value, attempts);
 
                // If the request did not raise any communication errors, we can return the response.
                if (!should_retry)
                    return response;
 
                // In stream mode, we can't automatically retry the request (the stream has already been
                // written to by the underlying RestSharp call and is tarnished) so we must raise an error.
                if (responseStreamReader != null)
                    throw ServerErrorExceptionHelper(response, response.ErrorException, null,
                        "The initial request could not be completed due to a temporary " +
                        "communication error. Please reset the stream and try again. " +
                        "The error message was: " + response.ErrorMessage);
 
                // If nothing above threw an exception, and should_retry is true, then the initial
                // request failed and the issue might be resolved by attempting the same request again.
 
                // This is not a standard feature of REST client libraries, but it
                // reduces the overhead for client applications (like excel) by abstracting
                // overarching configuration errors that would impact all individual requests.
            } while (attempts++ <= MaxRequestRetries);
 
            // If we exceeded the maximum number of retries and never returned, raise an error.
            throw ServerErrorExceptionHelper(response, response.ErrorException, null,
                "The request encountered what appears to be a temporary error, " +
                "but continues to fail after " + MaxRequestRetries + " consecutive attempts. " +
                "The final error message was: " + response.ErrorMessage);
        }
 
        private static IRestResponse ExecuteRequest(IRestClient client, IRestRequest request)
        {
#if DEBUG
            if (RequestLogging)
                DebugRestRequest(request);
#endif
            IRestResponse response = client.Execute(request);
#if DEBUG
            // Only log the entire reset response if RequestLogging is turned on
            // or if the response was an error.
            if (RequestLogging || !response.IsSuccessful())
                DebugRestResponse(response);
#endif
            return response;
        }
        #endregion Basic REST Request
 
        #region IRestResponse deserialization
        public static T ExtractRestResponse<T>(IRestResponse response)
        {
            return ExtractRestResponseHelper(response, typeof(T),
                () => Converter.Deserialize<T>(response));
        }
 
        public static object ExtractRestResponse(IRestResponse response, Type deserializeType)
        {
            return ExtractRestResponseHelper(response, deserializeType,
                () => Converter.Deserialize(response.Content, deserializeType));
        }
        #endregion IRestResponse deserialization
 
        #region Private Helper Methods
        #region Request Helpers
        private static void PrepareRequestParameters(
            ref RestRequest request,
            IEnumerable<Parameter> requestParameters)
        {
            RequestParameters parameters = new RequestParameters(requestParameters);
 
            // Check if an overriding Authorization header has been specified
            if (!parameters.Any(p => p.Type == ParameterType.HttpHeader && p.Name.Equals("Authorization")))
                if (AuthenticationToken is BearerAuthenticationToken bearerToken)
                {
                    request.AddHeader("Authorization", $"Bearer {bearerToken.access_token}");
                }
                else if (AuthenticationToken is BasicAuthenticationToken basicToken)
                {
                    request.AddHeader("Authorization", $"Basic {basicToken.access_token}");
                }
 
            // Hack: Rather than have a separate optional argument for a request body to be
            // serialized to JSON, we allow the Rest body parameter to be passed in as an
            // object (usually it can only be a string), then we serialize it to JSON for them.
            IEnumerable<Parameter> requestBodyParameters =
                parameters.Where(param => param.Type == ParameterType.RequestBody).ToList();
            if (requestBodyParameters.Count() > 1)
                throw new ArgumentException("More than one RequestBody parameter was supplied.");
            Parameter requestBodyParameter = requestBodyParameters.FirstOrDefault();
 
            // Only serialize if we are sure it's meant to be JSON, but the body is not yet a string.
            if (requestBodyParameter != null && requestBodyParameter.Name == JSON_CONTENT_TYPE &&
                requestBodyParameter.Value.GetType() != typeof(string))
            {
                string serialized = Converter.Serialize(requestBodyParameter.Value);
 
                // Remove the RequestBody parameter now that we've attached it to the request.
                parameters.Remove(requestBodyParameter);
                parameters.Add(requestBodyParameter = new Parameter
                {
                    Name = JSON_CONTENT_TYPE,
                    ContentType = JSON_CONTENT_TYPE,
                    Value = serialized,
                    Type = ParameterType.RequestBody
                });
            }
 
            // TODO: Experimental - zip the request body if it exceeds a certain size
            //if (requestBodyParameter?.Value is string contentString && contentString.Length > 1)
            //{
            //    // TODO: Either set the Content-Encoding
            //    request.AddParameter("Content-Encoding", "gzip", RestSharp.ParameterType.HttpHeader);
            //    // TODO: Or set the Content-Type (but probably not both)
            //    requestBodyParameter.Name = requestBodyParameter.ContentType = "application/gzip";
 
            //    MemoryStream dataStream = new MemoryStream();
            //    using (GZipStream zipStream = new GZipStream(dataStream, CompressionLevel.Fastest))
            //    using (StreamWriter writer = new StreamWriter(zipStream))
            //    {
            //        writer.Write(contentString);
            //    }
            //    requestBodyParameter.Value = dataStream.ToArray();
            //}
 
            request.Parameters.AddRange(parameters);
        }
        #endregion Request Helpers
 
        #region Response Helpers
        private static string CheckForRedirect(IRestResponse response, IRestClient client)
        {
            // Determine whether we've been issued a redirect request.
            bool redirected = (int)response.StatusCode >= 300 && (int)response.StatusCode < 400;
            if (!redirected)
                return null;
 
            string newLocation = response.Headers.FirstOrDefault(
                h => h.Name.Equals("Location", StringComparison.OrdinalIgnoreCase))?.Value?.ToString();
            string message = "The server returned a redirect status (" + response.StatusCode + ")";
            Debug.WriteLine(message);
            if (newLocation == null)
                throw ServerErrorExceptionHelper(response, null, null, message +
                    ", but did specify a redirect location.");
            // If the location is relative (presumably to the current host root), return it directly.
            if (Uri.IsWellFormedUriString(newLocation, UriKind.Relative))
                return newLocation;
            // If the location is absolute, parse it
            if (Uri.IsWellFormedUriString(newLocation, UriKind.Absolute))
            {
                Uri newUri = new Uri(newLocation, UriKind.Absolute);
                // For now, assume it is unsafe to automatically redirect to a new host.
                // The user will have to follow the redirect themselves manually if they trust it.
                if (newUri.Host != client.BaseUrl.Host)
                    throw ServerErrorExceptionHelper(response, null, null, message +
                        ", but wants to switch to a new host URL (" + newUri.Host + "). " +
                        "You will have to manually reconfigure your client to use this " +
                        "new address if you trust it.");
                // Return just the path (no host) to be used for the next request.
                return newUri.AbsolutePath;
            }
            throw ServerErrorExceptionHelper(response, null, null, message +
                ", but the redirect location was not well formed: " + newLocation);
        }
 
        private static bool CheckIncompleteResponse(IRestResponse response,
            DateTime requestStartTime, int sequentialAttempts)
        {
            // Check if there were any authentication errors, and handle them appropriately
            // Will return should_retry=true if the initial request failed but we can attempt
            // this same request again (either because new credentials have been supplied,
            // or if a temporary SSL failure may have occurred).
            if (TryHandleAuthenticationErrors(response, sequentialAttempts))
                return true;
 
            // If the request completed successfully, we're done here
            if (response.ResponseStatus == ResponseStatus.Completed)
                return false;
 
            // If the request did not complete successfully, determine whether this is a temporary
            // error (and return true to allow retry of the request) or raise a meaningful exception.
 
            // The following exception types occur sporadically and should be automatically retried:
            if (response.ErrorException is IOException || response.ErrorException is SocketException)
                return true;
 
            // Certain types of WebExceptions are also sporadic
            if (response.ErrorException is WebException asWebException)
            {
                Debug.WriteLine("WebException Occurred with Status: " +
                    $"{asWebException.Status}\n{asWebException}");
 
                // Timeouts are permanent failures (since the user configures the timeout), but
                // some timeouts don't raise a meaningful exception.
                if (asWebException.Status == WebExceptionStatus.Timeout)
                    return SuppressTimeoutOrThrow(response, requestStartTime);
 
                // Sometimes a non-'timeout' error can occur because the timeout has elapsed.
                // Detect these cases and treat them as a timeout.
                // (See https://support.microsoft.com/en-us/help/2007873 )
                // TODO: Such checks are culture (language) specific and may not work in other
                //       locales, Framework error messages might be translated.
                const string socketTimeoutError = "A connection attempt failed because the " +
                    "connected party did not properly respond after a period of time, " +
                    "or established connection failed because connected host has failed to respond";
                if ((asWebException.Status == WebExceptionStatus.KeepAliveFailure ||
                    asWebException.Status == WebExceptionStatus.ReceiveFailure) && (
                    asWebException.InnerException?.InnerException?.Message.Equals(
                        socketTimeoutError, StringComparison.CurrentCultureIgnoreCase) ?? false))
                    return SuppressTimeoutOrThrow(response, requestStartTime);
                
                // If the status is indicative of a temporary error, suggest a retry
                if (TemporaryFailureStatuses.Contains(asWebException.Status))
                    return true;
            }
            else if (response.ErrorMessage.Contains("The operation has timed out"))
                return SuppressTimeoutOrThrow(response, requestStartTime);
            // For all other errors, return the message from the server.
            throw ServerErrorExceptionHelper(response, response.ErrorException, null,
                $"Server Communication Error - {response.ErrorMessage}");
        }
 
        private static bool SuppressTimeoutOrThrow(IRestResponse response, DateTime requestStartTime)
        {
            TimeSpan elapsed = DateTime.UtcNow - requestStartTime;
            string logPrefix = $"The request timed out after {elapsed.TotalMilliseconds} ms";
 
            // Occasionally, a low-level timeout is raised before the response object is created.
            // This is likely not an "actual" timeout and can be retried.
            if (response?.Request == null)
            {
                Debug.WriteLine($"{logPrefix}, but the request object is empty. " +
                    "This likely indicates that a low-level timeout occurred before " +
                    "the response could be instantiated. The request will be retried.");
                return true;
            }
 
            // If the timeout hasn't actually elapsed as far as we can tell, suggest a retry
            if (response.Request.Timeout > elapsed.TotalMilliseconds)
            {
                Debug.WriteLine($"{logPrefix}, but the configured timeout period " +
                    $"({response.Request.Timeout} ms) hasn't elapsed. " +
                    "This likely indicates a timeout occurred in the underlying TCP protocol. " +
                    "The request will be retried.");
                return true;
            }
 
            // Otherwise, re-raise as a timeout exception since that is more meaningful.
            Debug.WriteLine($"{logPrefix}. Re-raising the error returned (" +
                $"{response.ErrorException.GetType().NiceTypeName()}) as a RequestTimeoutException.");
            string message = $"{logPrefix}. The requested timeout was {response.Request.Timeout} ms. " +
                "If this is a large request, you may need to wait longer for a response. " +
                "Check your API.DefaultRequestTimeout or set a timeout directly in your API call.";
            throw new RequestTimeoutException(message, response.ErrorException, response);
        }
 
        private static T ExtractRestResponseHelper<T>(
            IRestResponse response,
            Type deserializeType,
            Func<T> deserializeAction)
        {
            Exception parsingException = null;
            if (response.IsSuccessful())
            {
                // See if the response can be parsed into the target object type.
                try
                {
                    T retVal;
                    // Response is empty, return null
                    if (response.StatusCode == HttpStatusCode.NoContent)
                        retVal = default(T);
                    // Special case: if user requests the response type of string,
                    // return the content directly without attempting to serialize it.
                    else if (deserializeType == typeof(string) || response.Content == null)
                        retVal = (T)Convert.ChangeType(response.Content, typeof(T));
                    // Similarly, if the user requests an IRestResponse result, return it directly.
                    else if (deserializeType.IsAssignableFrom(typeof(IRestResponse)))
                        retVal = (T)response;
                    // Otherwise, deserialize the content to the requested type
                    else
                        retVal = deserializeAction();
#if DEBUG
                    if (RequestLogging)
                    {
                        Debug.WriteLine("The response was successfully parsed and returned.\n");
                    }
#endif
                    return retVal;
                }
                catch (Exception e)
                {
                    string parseMessage =
                        "The response could not be parsed into the desired type: \"" +
                        deserializeType.NiceTypeName() + "\"";
#if DEBUG
                    Debug.WriteLine(parseMessage + (RequestLogging ? "\n" : ""));
#endif
                    parsingException = new Exception(parseMessage, e);
                }
            }
#if DEBUG
            // If the request failed and request info level logging is turned off, then the request
            // that failed won't have been logged yet, so log it now at the warning level.
            if (!RequestLogging)
            {
                Debug.WriteLine("The following request failed:");
                DebugRestRequest(response.Request);
            }
#endif
 
            // See if the response can be parsed into an error object.
            ServerError serverError = ExtractErrorResponse(response, ref parsingException);
 
            // Throw an exception because the response was not successful.
            // If we met a specific parsing exception, include it.
            // If we parsed out a serverError object, include it.
            throw ServerErrorExceptionHelper(response, parsingException, serverError);
        }
 
        private static ServerError ExtractErrorResponse(
            IRestResponse response,
            ref Exception parsingException)
        {
            bool errorResponseExpected =
                // Special case, we don't expect an error body for 503 responses
                response.StatusCode != HttpStatusCode.ServiceUnavailable &&
                // Otherwise, we expect non-successful responses to contain a ServerError
                !response.IsSuccessful();
 
            try
            {
                // Handle empty responses upfront rather letting Deserialize throw an exception.
                if (String.IsNullOrWhiteSpace(response.Content))
                {
                    // If the response is empty and we aren't expecting an error object, return
                    if (!errorResponseExpected)
                        return null;
                    // Otherwise, complain that the response body was empty.
                    throw new ArgumentException(
                        "The server response was an error but no error details were supplied.");
                }
 
                ServerError serverError = Converter.Deserialize<ServerError>(response);
                if (serverError.message == null && serverError.traceback == null)
                    throw new ArgumentException("Response contain no ServerError properties.");
#if DEBUG
                Debug.WriteLine("The response was received but contained a server error.");
                if (RequestLogging) Debug.WriteLine("");
#endif
                return serverError;
            }
            catch (Exception e)
            {
                // If we weren't expecting an error response, ignore the failed attempt to get it.
                // This happens in scenarios where we fail to parse the successful response, but
                // before returning that parsing exception, we want to make sure the server didn't
                // actually return an error response object in spite of the successful status code.
                if (!errorResponseExpected)
                    return null;
                // If we were expecting an error response, and encountered an exception while
                // trying to parse one out, return the parsing exception and log an error.
                parsingException = e;
#if DEBUG
                Debug.WriteLine("The response was received but could not be parsed.");
                if (RequestLogging) Debug.WriteLine("");
#endif
                return null;
            }
        }
        #endregion Response Helpers
        #endregion Private Helper Methods
    }
}