Update documentation

docs/docs/api-reference/responses/api-rate-limits.md

@@ -0,0 +1,64 @@
+---
+title: ApiRateLimits
+---
+
+The `ApiRateLimits` class represents the rate limits of the GoCardless API.
+
+## Properties
+
+### `RequestLimit` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the maximum number of allowed requests within the defined time window.
+
+### `RemainingRequests` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the number of remaining requests you can make in the current time window.
+
+### `RemainingSecondsInTimeWindow` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the time remaining in the current time window (in seconds).
+
+### `RequestLimitAccountsEndpoint` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the maximum number of allowed requests to the [AccountsEndpoint](/docs/api-reference/endpoints/accounts-endpoint) within the defined time window.
+
+### `RemainingRequestsAccountsEndpoint` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the number of remaining requests to the [AccountsEndpoint](/docs/api-reference/endpoints/accounts-endpoint) you can make in the current time window.
+
+### `RemainingSecondsInTimeWindowAccountsEndpoint` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the time remaining in the current time window (in seconds) for requests to the [AccountsEndpoint](/docs/api-reference/endpoints/accounts-endpoint).
+
+## Constructor
+
+```csharp
+public ApiRateLimits(int requestLimit, int remainingRequests, int remainingTimeInTimeWindow,
+      int maxAccountRequests, int remainingAccountRequests, int remainingTimeInAccountTimeWindow)
+```
+
+### Parameters
+
+#### `requestLimit` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the maximum number of allowed requests within the defined time window.
+
+#### `remainingRequests` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the number of remaining requests you can make in the current time window.
+
+#### `remainingSecondsInTimeWindow` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the time remaining in the current time window (in seconds).
+
+#### `requestLimitAccountsEndpoint` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the maximum number of allowed requests to the [AccountsEndpoint](/docs/api-reference/endpoints/accounts-endpoint) within the defined time window.
+
+#### `remainingRequestsAccountsEndpoint` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the number of remaining requests to the [AccountsEndpoint](/docs/api-reference/endpoints/accounts-endpoint) you can make in the current time window.
+
+#### `remainingSecondsInTimeWindowAccountsEndpoint` - [int](https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-int32)
+
+Indicates the time remaining in the current time window (in seconds) for requests to the [AccountsEndpoint](/docs/api-reference/endpoints/accounts-endpoint).

docs/docs/api-reference/responses/nordigen-api-response.md

@@ -22,10 +22,15 @@ The result returned by the API. Null if the the HTTP response was not successful
 
 The error returned by the API. Null if the HTTP response was successful.
 
+### `RateLimits` - [ApiRateLimits](/docs/api-reference/responses/api-rate-limits)
+
+The rate limits of the GoCardless API.
+
 ## Constructor
 
 ```csharp
-public NordigenApiResponse(HttpStatusCode statusCode, bool isSuccess, TResult? result, TError? apiError)
+public NordigenApiResponse(HttpStatusCode statusCode, bool isSuccess,
+      TResult? result, TError? apiError,  ApiRateLimits rateLimits)
 ```
 
 ### Parameters
@@ -46,6 +51,10 @@ The result returned by the API. Null if the the HTTP response was not successful
 
 The error returned by the API. Null if the HTTP response was successful.
 
+#### `rateLimits` - [ApiRateLimits](/docs/api-reference/responses/api-rate-limits)
+
+The rate limits of the GoCardless API.
+
 ## Handling the `NordigenApiResponse` type
 
 To learn more about how to best work with the `NordigenApiResponse` type see the [Handling API responses](/docs/handling-api-responses) guide.

docs/docs/handling-rate-limits.md

@@ -0,0 +1,31 @@
+---
+title: Handling Rate Limits
+---
+
+The GoCardless API has [rate limits](https://bankaccountdata.zendesk.com/hc/en-gb/articles/11529637772188-Bank-Account-Data-API-Rate-Limits) depending on the endpoint you are using. With most endpoints you shouldn't run into problems since these limits are usually high enough for most uses.
+
+The [Accounts endpoint](/docs/api-reference/endpoints/accounts-endpoint) has very tight limitations though. It currently has a limit of 10 requests a day per access scope. That means 10 requests to each of the [details](/docs/api-reference/endpoints/accounts-endpoint#getaccountdetails), [balances](/docs/api-reference/endpoints/accounts-endpoint#getbalances) and [transactions](/docs/api-reference/endpoints/accounts-endpoint#gettransactions) endpoints. In the future this limit will be lowered to 4 per day (no date on this as of now).
+
+Unsuccessful requests to the API will count towards the general rate limits but not the more stringent limits of the [Accounts endpoint](/docs/api-reference/endpoints/accounts-endpoint). Only successful requests will count towards those.
+
+## Checking API rate limits
+
+You can check the rate limits as well as remaining requests with each request you make to the API. The property [`NordigenApiResponse.RateLimits`](/docs/api-reference/responses/nordigen-api-response#ratelimits---apiratelimits) will hold the returned information about the current API limits.
+
+You can check the limits as follows:
+
+```csharp
+// Execute the request you want to make:
+var bankAccountDetailsResponse = await client.AccountsEndpoint.GetAccountDetails(accountId);
+
+Console.WriteLine(bankAccountDetailsResponse.RateLimits.RequestLimit);
+Console.WriteLine(bankAccountDetailsResponse.RateLimits.RemainingRequests);
+Console.WriteLine(bankAccountDetailsResponse.RateLimits.RemainingSecondsInTimeWindow);
+Console.WriteLine(bankAccountDetailsResponse.RateLimits.RequestLimitAccountsEndpoint);
+Console.WriteLine(bankAccountDetailsResponse.RateLimits.RemainingRequestsAccountsEndpoint);
+Console.WriteLine(bankAccountDetailsResponse.RateLimits.RemainingSecondsInTimeWindowAccountsEndpoint);
+```
+
+It's important to handle these limits so your applications user experience isn't degraded. Refreshing data from bank accounts should be handled consciously, so you don't use up all your requests in a short time frame and aren't able to update for the rest of the day.
+
+If you are a company with a contract with GoCardless you can probably get in contact with their team about increasing these limits.

docs/release-notes/v10_1_0.md

@@ -0,0 +1,9 @@
+---
+slug: v10.1.0
+title: v10.1.0
+date: 2024-08-19T00:00
+---
+
+Added the ability to check newly introduced rate limits in the GoCardless API.
+
+Please refer to the [documentation](/docs/handling-rate-limits) for more information. You can also see the [announcement from GoCardless](https://bankaccountdata.zendesk.com/hc/en-gb/articles/11529584398236-Bank-API-Rate-Limits-and-Rate-Limit-Headers).

docs/sidebars.ts

@@ -6,6 +6,7 @@ const sidebars: SidebarsConfig = {
     "quickstart-guide",
     "handling-api-responses",
     "handling-authentication-tokens",
+    "handling-rate-limits",
     "using-a-different-base-address",
     "usage-with-older-dotnet-versions",
     "testing",
@@ -38,6 +39,7 @@ const sidebars: SidebarsConfig = {
             "api-reference/responses/address",
             "api-reference/responses/agreement",
             "api-reference/responses/amount-currency-pair",
+            "api-reference/responses/api-rate-limits",
             "api-reference/responses/balance",
             "api-reference/responses/balance-type",
             "api-reference/responses/bank-account",

src/RobinTTY.NordigenApiClient/Models/Errors/CreateAgreementError.cs

@@ -1,6 +1,5 @@
 using System.Text.Json.Serialization;
 using RobinTTY.NordigenApiClient.JsonConverters;
-using RobinTTY.NordigenApiClient.Models.Requests;
 using RobinTTY.NordigenApiClient.Models.Responses;
 
 namespace RobinTTY.NordigenApiClient.Models.Errors;

src/RobinTTY.NordigenApiClient/Models/Errors/CreateRequisitionError.cs

@@ -1,6 +1,5 @@
 using System.Text.Json.Serialization;
 using RobinTTY.NordigenApiClient.JsonConverters;
-using RobinTTY.NordigenApiClient.Models.Requests;
 using RobinTTY.NordigenApiClient.Models.Responses;
 
 namespace RobinTTY.NordigenApiClient.Models.Errors;

src/RobinTTY.NordigenApiClient/Models/Responses/ApiRateLimits.cs

@@ -24,46 +24,46 @@ public class ApiRateLimits
     /// Indicates the maximum number of allowed requests to the <see cref="AccountsEndpoint"/>
     /// within the defined time window.
     /// </summary>
-    public int MaxAccountRequests { get; set; }
+    public int RequestLimitAccountsEndpoint { get; set; }
     /// <summary>
     /// Indicates the number of remaining requests to the <see cref="AccountsEndpoint"/>
     /// you can make in the current time window.
     /// </summary>
-    public int RemainingAccountRequests { get; set; }
+    public int RemainingRequestsAccountsEndpoint { get; set; }
     /// <summary>
     /// Indicates the time remaining in the current time window (in seconds) for requests
     /// to the <see cref="AccountsEndpoint"/>.
     /// </summary>
-    public int RemainingSecondsInAccountTimeWindow { get; set; }
+    public int RemainingSecondsInTimeWindowAccountsEndpoint { get; set; }
 
     /// <summary>
     /// Creates a new instance of <see cref="ApiRateLimits" />.
     /// </summary>
     /// <param name="requestLimit">Indicates the maximum number of allowed requests within the defined time window.</param>
     /// <param name="remainingRequests">Indicates the number of remaining requests you can make in the current time window.</param>
-    /// <param name="remainingTimeInTimeWindow">Indicates the time remaining in the current time window (in seconds).</param>
-    /// <param name="maxAccountRequests">Indicates the maximum number of allowed requests to the <see cref="AccountsEndpoint"/>
+    /// <param name="remainingSecondsInTimeWindow">Indicates the time remaining in the current time window (in seconds).</param>
+    /// <param name="requestLimitAccountsEndpoint">Indicates the maximum number of allowed requests to the <see cref="AccountsEndpoint"/>
     /// within the defined time window.</param>
-    /// <param name="remainingAccountRequests">Indicates the number of remaining requests to the <see cref="AccountsEndpoint"/>
+    /// <param name="remainingRequestsAccountsEndpoint">Indicates the number of remaining requests to the <see cref="AccountsEndpoint"/>
     /// you can make in the current time window.</param>
-    /// <param name="remainingTimeInAccountTimeWindow">Indicates the time remaining in the current time window (in seconds) for requests
+    /// <param name="remainingSecondsInTimeWindowAccountsEndpoint">Indicates the time remaining in the current time window (in seconds) for requests
     /// to the <see cref="AccountsEndpoint"/>.</param>
-    public ApiRateLimits(int requestLimit, int remainingRequests, int remainingTimeInTimeWindow, int maxAccountRequests,
-        int remainingAccountRequests, int remainingTimeInAccountTimeWindow)
+    public ApiRateLimits(int requestLimit, int remainingRequests, int remainingSecondsInTimeWindow, int requestLimitAccountsEndpoint,
+        int remainingRequestsAccountsEndpoint, int remainingSecondsInTimeWindowAccountsEndpoint)
     {
         RequestLimit = requestLimit;
         RemainingRequests = remainingRequests;
-        RemainingSecondsInTimeWindow = remainingTimeInTimeWindow;
-        MaxAccountRequests = maxAccountRequests;
-        RemainingAccountRequests = remainingAccountRequests;
-        RemainingSecondsInAccountTimeWindow = remainingTimeInAccountTimeWindow;
+        RemainingSecondsInTimeWindow = remainingSecondsInTimeWindow;
+        RequestLimitAccountsEndpoint = requestLimitAccountsEndpoint;
+        RemainingRequestsAccountsEndpoint = remainingRequestsAccountsEndpoint;
+        RemainingSecondsInTimeWindowAccountsEndpoint = remainingSecondsInTimeWindowAccountsEndpoint;
     }
 
     /// <summary>
     /// Creates a new instance of <see cref="ApiRateLimits" />.
     /// </summary>
     /// <param name="headers">The headers of the HTTP response containing the rate limit information.</param>
-    public ApiRateLimits(HttpResponseHeaders headers)
+    public ApiRateLimits(HttpHeaders headers)
     {
         headers.TryGetValues("HTTP_X_RATELIMIT_LIMIT", out var requestLimitInTimeWindow);
         headers.TryGetValues("HTTP_X_RATELIMIT_REMAINING", out var remainingRequestsInTimeWindow);
@@ -75,8 +75,8 @@ public ApiRateLimits(HttpResponseHeaders headers)
         RequestLimit = requestLimitInTimeWindow != null ? int.Parse(requestLimitInTimeWindow.First()) : 0;
         RemainingRequests = remainingRequestsInTimeWindow != null ? int.Parse(remainingRequestsInTimeWindow.First()) : 0;
         RemainingSecondsInTimeWindow = remainingTimeInTimeWindow != null ? int.Parse(remainingTimeInTimeWindow.First()) : 0;
-        MaxAccountRequests = maxAccountRequestsInTimeWindow != null ? int.Parse(maxAccountRequestsInTimeWindow.First()) : 0;
-        RemainingAccountRequests = remainingAccountRequestsInTimeWindow != null ? int.Parse(remainingAccountRequestsInTimeWindow.First()) : 0;
-        RemainingSecondsInAccountTimeWindow = remainingTimeInAccountTimeWindow != null ? int.Parse(remainingTimeInAccountTimeWindow.First()) : 0;
+        RequestLimitAccountsEndpoint = maxAccountRequestsInTimeWindow != null ? int.Parse(maxAccountRequestsInTimeWindow.First()) : 0;
+        RemainingRequestsAccountsEndpoint = remainingAccountRequestsInTimeWindow != null ? int.Parse(remainingAccountRequestsInTimeWindow.First()) : 0;
+        RemainingSecondsInTimeWindowAccountsEndpoint = remainingTimeInAccountTimeWindow != null ? int.Parse(remainingTimeInAccountTimeWindow.First()) : 0;
     }
 }

src/RobinTTY.NordigenApiClient/RobinTTY.NordigenApiClient.csproj

@@ -16,7 +16,7 @@
         <PackageTags>Nordigen; API; client</PackageTags>
         <PackageReleaseNotes>$([System.IO.File]::ReadAllText("$(MSBuildProjectDirectory)/release-notes.txt"))</PackageReleaseNotes>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
-        <Version>10.0.0</Version>
+        <Version>10.1.0</Version>
         <IncludeSymbols>true</IncludeSymbols>
         <SymbolPackageFormat>snupkg</SymbolPackageFormat>
         <UserSecretsId>12f53312-dcef-47c5-bc2e-0ce6f74609a6</UserSecretsId>

src/RobinTTY.NordigenApiClient/release-notes.txt

@@ -1,2 +1,2 @@
-Add the ability to check newly introduced rate limits in the GoCardless API.
+Added the ability to check newly introduced rate limits in the GoCardless API.
 Also see: https://bankaccountdata.zendesk.com/hc/en-gb/articles/11529584398236-Bank-API-Rate-Limits-and-Rate-Limit-Headers