From 0c855484f8380264eb882edee7fa54959cc63923 Mon Sep 17 00:00:00 2001 From: Matt Raffel Date: Tue, 3 Jun 2025 10:15:23 -0600 Subject: [PATCH] more updates Signed-off-by: Matt Raffel --- portal/docs/changelog.md | 2 + portal/docs/overview/authentication.md | 2 +- .../current/overview/authentication.md | 2 +- .../current/overview/authentication.md | 2 +- samples/dotnet/get.loans/Program.cs | 60 +++++++++++++++++-- .../KivaPartnerAPI.postman_collection.json | 2 +- samples/typescript/README.md | 2 +- 7 files changed, 62 insertions(+), 10 deletions(-) diff --git a/portal/docs/changelog.md b/portal/docs/changelog.md index ea3a791..7cf0fd5 100644 --- a/portal/docs/changelog.md +++ b/portal/docs/changelog.md @@ -8,6 +8,8 @@ sidebar_position: 1 This changelog lists all additions and updates to the Kiva Partner API, in chronological order. +## June 1, 2025 +1. Additional corrections to samples and documentation for endpoint information. ## April 30, 2025 1. updated URLS to reflect changes in Kiva infrastructure diff --git a/portal/docs/overview/authentication.md b/portal/docs/overview/authentication.md index 90bd31c..3e59e83 100644 --- a/portal/docs/overview/authentication.md +++ b/portal/docs/overview/authentication.md @@ -10,7 +10,7 @@ The new Partner API is accessible using an Oauth2 JWT obtained from Kiva’s aut ### Sample Request (test environment) ```json -1 curl --location --request POST 'https://auth-stage.kiva.org/oauth/token' \ +1 curl --location --request POST 'https://auth.staging.kiva.org/oauth/token' \ 2 --header 'Accept: application/json' \ 3 --header 'Content-Type: application/x-www-form-urlencoded' \ 4 --data-urlencode 'grant_type=client_credentials' \ diff --git a/portal/i18n/es/docusaurus-plugin-content-docs/current/overview/authentication.md b/portal/i18n/es/docusaurus-plugin-content-docs/current/overview/authentication.md index 6dd0a2c..6efc43f 100644 --- a/portal/i18n/es/docusaurus-plugin-content-docs/current/overview/authentication.md +++ b/portal/i18n/es/docusaurus-plugin-content-docs/current/overview/authentication.md @@ -11,7 +11,7 @@ Se puede acceder a la nueva API de socios mediante un Oauth2 JWT obtenido del se ### Solicitud de muestra (entorno de prueba) ```json -1 curl --location --request POST 'https://auth-stage.kiva.org/oauth/token' \ +1 curl --location --request POST 'https://auth.staging.kiva.org/oauth/token' \ 2 --header 'Accept: application/json' \ 3 --header 'Content-Type: application/x-www-form-urlencoded' \ 4 --data-urlencode 'grant_type=client_credentials' \ diff --git a/portal/i18n/fr/docusaurus-plugin-content-docs/current/overview/authentication.md b/portal/i18n/fr/docusaurus-plugin-content-docs/current/overview/authentication.md index 0e5abe9..7976e3e 100644 --- a/portal/i18n/fr/docusaurus-plugin-content-docs/current/overview/authentication.md +++ b/portal/i18n/fr/docusaurus-plugin-content-docs/current/overview/authentication.md @@ -11,7 +11,7 @@ Il est possible d'accéder à la nouvelle API des partenaires via un Oauth2 JWT ### Demande d'échantillon (environnement de test) ```json -1 curl --location --request POST 'https://auth-stage.kiva.org/oauth/token' \ +1 curl --location --request POST 'https://auth.staging.kiva.org/oauth/token' \ 2 --header 'Accept: application/json' \ 3 --header 'Content-Type: application/x-www-form-urlencoded' \ 4 --data-urlencode 'grant_type=client_credentials' \ diff --git a/samples/dotnet/get.loans/Program.cs b/samples/dotnet/get.loans/Program.cs index 32404d6..7457aa6 100644 --- a/samples/dotnet/get.loans/Program.cs +++ b/samples/dotnet/get.loans/Program.cs @@ -18,10 +18,29 @@ string AuthDomain = "auth.staging.kiva.org"; // URI only, no protocol, no path string PartnerDomain = "partnerapi.staging.kiva.org"; // same as above, no protocol, no path +// for the loans endpoint, the status is required. See docs for valid values +string loanStaus = "payingBack"; +int offset = 0; +int limit = 100; + +// Valid loan status values +string[] validLoanStatuses = new string[] { + "deleted", "issue", "payingBack", "issue_revising", "issue_approving", + "reviewed", "fundRaising", "refunded", "raised", "ended", "defaulted", + "expired", "inactive_expired" +}; // --------------------------------------------------------------------------- // functions +void ShowHelpAndExit() +{ + Console.WriteLine("\r\nUsage: dotnet run [--loanStatus ] [--limit ]"); + Console.WriteLine(" --loanStatus: Optional. Valid values: " + string.Join(", ", validLoanStatuses)); + Console.WriteLine(" --limit: Optional. Integer between 0 and 3000."); + Console.WriteLine("\r\n"); + Environment.Exit(1); +} // --------------------------------------------------------------------------- // Please see the auth sample for discussion of how the authorization is expected to work @@ -47,9 +66,7 @@ async Task GetAuthorizationToken() if (response.StatusCode == HttpStatusCode.OK) { using Stream responseBody = await response.Content.ReadAsStreamAsync(); - var kivaAuthorization = await JsonSerializer.DeserializeAsync(responseBody); - - // TODO: parse out auth token and partner id + var kivaAuthorization = await JsonSerializer.DeserializeAsync(responseBody); PartnerId = kivaAuthorization.PartnerId; BearerToken = kivaAuthorization.AuthToken; @@ -72,7 +89,9 @@ async Task GetLoans() new MediaTypeWithQualityHeaderValue("application/json")); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", BearerToken); - var response = await client.GetAsync($"https://{PartnerDomain}/v3/partner/{PartnerId}/loans"); + // note: filter parameters, see https://partnerapi.staging.kiva.org/swagger-ui/index.html#/partners/loansRoute + Console.WriteLine($"Getting loans for partner {PartnerId} with status {loanStaus}, offset {offset}, limit {limit}"); + var response = await client.GetAsync($"https://{PartnerDomain}/v3/partner/{PartnerId}/loans?status={loanStaus}&offset={offset}&limit={limit}"); var json = await response.Content.ReadAsStringAsync(); @@ -91,10 +110,41 @@ async Task GetLoans() // Program execution // --------------------------------------------------------------------------- +// Parse command line arguments +for (int i = 0; i < args.Length; i++) +{ + if (args[i] == "--loanStatus" && i + 1 < args.Length) + { + string statusArg = args[i + 1]; + if (Array.IndexOf(validLoanStatuses, statusArg) == -1) + { + Console.WriteLine($"Invalid loanStatus: {statusArg}"); + ShowHelpAndExit(); + } + loanStaus = statusArg; + i++; + } + else if (args[i] == "--limit" && i + 1 < args.Length) + { + if (!int.TryParse(args[i + 1], out int parsedLimit) || parsedLimit < 0 || parsedLimit > 3000) + { + Console.WriteLine($"Invalid limit: {args[i + 1]}"); + ShowHelpAndExit(); + } + limit = parsedLimit; + i++; + } + else + { + Console.WriteLine($"Unknown or incomplete argument: {args[i]}"); + ShowHelpAndExit(); + } +} + Console.WriteLine("Kiva Partner API for listing loans"); Console.WriteLine(" -- Step 1 Getting authorization token"); await GetAuthorizationToken(); Console.WriteLine(" -- Step 2 listing the loans for the partner"); -await GetLoans(); \ No newline at end of file +await GetLoans(); diff --git a/samples/postman/KivaPartnerAPI.postman_collection.json b/samples/postman/KivaPartnerAPI.postman_collection.json index 97711be..0ecd2d8 100644 --- a/samples/postman/KivaPartnerAPI.postman_collection.json +++ b/samples/postman/KivaPartnerAPI.postman_collection.json @@ -273,7 +273,7 @@ ] }, "url": { - "raw": "https://auth-stage.kiva.org/oauth/token", + "raw": "https://auth.staging.kiva.org/oauth/token", "protocol": "https", "host": [ "auth-stage", diff --git a/samples/typescript/README.md b/samples/typescript/README.md index 5768e08..7a680f0 100644 --- a/samples/typescript/README.md +++ b/samples/typescript/README.md @@ -13,7 +13,7 @@ using node `18.12.1` and npm `8.19.2`. ## Getting an authorization token example This example shows how to retrieve an auth token with the credentials provided. This example -demostrates using `https://auth-stage.kiva.org/oauth/token` api. +demostrates using `https://auth.staging.kiva.org/oauth/token` api. 1. run `npm run auth` [Code](./src/demo/auth.ts)