Add QueryWithResponse API (#38)

Author: kamranayub

IGDB.Tests/Games.cs

@@ -27,6 +27,25 @@ public async Task ShouldReturnResponseWithoutQuery()
       Assert.True(games.Length == 10);
     }
 
+    [Fact]
+    public async Task ShouldReturnResponseWithHeaders()
+    {
+      var games = await _api.QueryWithResponseAsync<Game>(IGDBClient.Endpoints.Games);
+
+      Assert.NotNull(games);
+      Assert.True(games.GetContent().Length == 10);
+
+      var rawCount = games.ResponseMessage.Headers.GetValues("x-count").First();
+
+      Assert.NotNull(rawCount);
+      Assert.True(int.Parse(rawCount) > 0);
+
+      var queryCount = games.GetQueryCount();
+
+      Assert.NotNull(queryCount);
+      Assert.True(queryCount > 0);
+    }
+
     [Fact]
     public async Task ShouldReturnResponseWithSingleGame()
     {
@@ -159,12 +178,12 @@ public async Task ShouldReturnGameWithDlc()
 
       Assert.NotEmpty(game.Dlcs.Ids);
     }
-    
+
     [Fact]
     public async Task ShouldReturnGameCount()
     {
       var gameCount = await _api.CountAsync(IGDBClient.Endpoints.Games, "where id = 4;");
-      
+
       Assert.NotNull(gameCount);
       Assert.Equal(1, gameCount.Count);
     }

IGDB/IGDBApi.cs

@@ -30,6 +30,16 @@ public interface IGDBApi
     [Post("/{endpoint}")]
     Task<T[]> QueryAsync<T>([Path] string endpoint, [Body] string query = null);
 
+    /// <summary>
+    /// Queries a standard IGDB endpoint with an APIcalypse query and returns the deserialized response along with the HttpResponseMessage. See endpoints in <see cref="IGDB.IGDBClient.Endpoints" />.
+    /// </summary>
+    /// <param name="endpoint">The IGDB endpoint name to query, see <see cref="IGDB.IGDBClient.Endpoints" /></param>
+    /// <param name="query">The APIcalypse query to send</param>
+    /// <typeparam name="T">The IGDB.Models.* entity to deserialize the response for.</typeparam>
+    /// <returns>RestEase Response containing the HttpResponseMessage and the array of IGDB models of the specified type</returns>
+    [Post("/{endpoint}")]
+    Task<Response<T[]>> QueryWithResponseAsync<T>([Path] string endpoint, [Body] string query = null);
+
     /// <summary>
     /// Queries a standard IGDB endpoint with an APIcalypse query. See endpoints in <see cref="IGDB.IGDBClient.Endpoints" />.
     /// </summary>
@@ -143,6 +153,27 @@ public async Task<T[]> QueryAsync<T>(string endpoint, string query = null)
       }
     }
 
+    public async Task<Response<T[]>> QueryWithResponseAsync<T>(string endpoint, string query = null)
+    {
+      try
+      {
+        return await _api.QueryWithResponseAsync<T>(endpoint, query);
+      }
+      catch (ApiException apiEx)
+      {
+        // Acquire new token and retry request (once)
+        if (IsInvalidTokenResponse(apiEx))
+        {
+          await _tokenManager.RefreshTokenAsync();
+
+          return await _api.QueryWithResponseAsync<T>(endpoint, query);
+        }
+
+        // Pass up any other exceptions
+        throw apiEx;
+      }
+    }
+
     public async Task<CountResponse> CountAsync(string endpoint, string query = null)
     {
       try

IGDB/ResponseExtensions.cs

@@ -0,0 +1,20 @@
+using System;
+using System.Linq;
+using System.Net.Http;
+using RestEase;
+
+namespace IGDB
+{
+  public static class ResponseExtensions
+  {
+    private const string CountHeader = "x-count";
+
+    /// <summary>
+    /// The value of the X-Count header for IGDB query endpoints, if it exists.
+    /// </summary>
+    public static int? GetQueryCount<T>(this Response<T> response)
+    {
+      return int.TryParse(response.ResponseMessage.Headers.GetValues(CountHeader).First(), out var count) ? count : (int?)null;
+    }
+  }
+}

README.md

@@ -69,6 +69,16 @@ game.Cover.Value.Width; // 756
 game.Cover.Value.Height;
 ```
 
+### Handling Query Counts
+
+You can use the `QueryWithResponse` API to return the raw `HttpResponseMessage` along with the deserialized response through `GetContent()`.
+
+There is an extension method available that will retrieve the `X-Count` header returned by IGDB on query endpoints. This avoids having to issue two requests to get the total results for a query. You also have full access to any headers through the `ResponseMessage` property.
+
+**See IGDB.Tests/Games.cs#ShouldReturnResponseWithHeaders** for an example test that covers this feature. You can also read more about the `Response<T>` [support in RestEase](https://github.com/canton7/RestEase?tab=readme-ov-file#return-types).
+
+Alternatively, you can also use the `CountAsync()` API to just retrieve the count for a query.
+
 ### Custom Token Management
 
 By default this client will request a OAuth bearer token on your behalf that is valid for 60 days and will store it statically **in memory**. If an invalid token is used and a 401 response is received, it will automatically acquire a new token and retry the request. See `TokenManagement.cs` for the default implementation.