From 01c546cb599f594456a4fb1a6ec5f7f8f26cee56 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Thu, 19 Dec 2024 02:41:20 +0000 Subject: [PATCH] chore(docs): update readme (#289) --- README.md | 112 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 64 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 7ae320b9..f22b4e76 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,9 @@ ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder() Alternately, set the environment with `MODERN_TREASURY_API_KEY`, `MODERN_TREASURY_ORGANIZATION_ID` or `MODERN_TREASURY_WEBHOOK_KEY`, and use `ModernTreasuryOkHttpClient.fromEnv()` to read from the environment. ```java +import com.moderntreasury.api.client.ModernTreasuryClient; +import com.moderntreasury.api.client.okhttp.ModernTreasuryOkHttpClient; + ModernTreasuryClient client = ModernTreasuryOkHttpClient.fromEnv(); // Note: you can also call fromEnv() from the client builder, for example if you need to set additional properties @@ -78,8 +81,7 @@ Read the documentation for more configuration options. ### Example: creating a resource -To create a new counterparty, first use the `CounterpartyCreateParams` builder to specify attributes, -then pass that to the `create` method of the `counterparties` service. +To create a new counterparty, first use the `CounterpartyCreateParams` builder to specify attributes, then pass that to the `create` method of the `counterparties` service. ```java import com.moderntreasury.api.models.Counterparty; @@ -93,12 +95,11 @@ Counterparty counterparty = client.counterparties().create(params); ### Example: listing resources -The Modern Treasury API provides a `list` method to get a paginated list of counterparties. -You can retrieve the first page by: +The Modern Treasury API provides a `list` method to get a paginated list of counterparties. You can retrieve the first page by: ```java import com.moderntreasury.api.models.Counterparty; -import com.moderntreasury.api.models.Page; +import com.moderntreasury.api.models.CounterpartyListPage; CounterpartyListPage page = client.counterparties().list(); for (Counterparty counterparty : page.items()) { @@ -109,6 +110,11 @@ for (Counterparty counterparty : page.items()) { Use the `CounterpartyListParams` builder to set parameters: ```java +import com.moderntreasury.api.models.CounterpartyListPage; +import com.moderntreasury.api.models.CounterpartyListParams; +import java.time.OffsetDateTime; +import java.util.List; + CounterpartyListParams params = CounterpartyListParams.builder() .afterCursor("after_cursor") .createdAtLowerBound(OffsetDateTime.parse("2019-12-27T18:11:19.117Z")) @@ -143,14 +149,14 @@ See [Pagination](#pagination) below for more information on transparently workin To make a request to the Modern Treasury API, you generally build an instance of the appropriate `Params` class. -In [Example: creating a resource](#example-creating-a-resource) above, we used the `CounterpartyCreateParams.builder()` to pass to -the `create` method of the `counterparties` service. +In [Example: creating a resource](#example-creating-a-resource) above, we used the `CounterpartyCreateParams.builder()` to pass to the `create` method of the `counterparties` service. -Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, -you can attach them using the `putAdditionalProperty` method. +Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, you can attach them using the `putAdditionalProperty` method. ```java -import com.moderntreasury.api.models.core.JsonValue; +import com.moderntreasury.api.core.JsonValue; +import com.moderntreasury.api.models.CounterpartyCreateParams; + CounterpartyCreateParams params = CounterpartyCreateParams.builder() // ... normal properties .putAdditionalProperty("secret_param", JsonValue.from("4242")) @@ -164,15 +170,19 @@ CounterpartyCreateParams params = CounterpartyCreateParams.builder() When receiving a response, the Modern Treasury Java SDK will deserialize it into instances of the typed model classes. In rare cases, the API may return a response property that doesn't match the expected Java type. If you directly access the mistaken property, the SDK will throw an unchecked `ModernTreasuryInvalidDataException` at runtime. If you would prefer to check in advance that that response is completely well-typed, call `.validate()` on the returned model. ```java +import com.moderntreasury.api.models.Counterparty; + Counterparty counterparty = client.counterparties().create().validate(); ``` ### Response properties as JSON -In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by -this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value. +In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value. ```java +import com.moderntreasury.api.core.JsonField; +import java.util.Optional; + JsonField field = responseObj._field(); if (field.isMissing()) { @@ -194,6 +204,8 @@ if (field.isMissing()) { Sometimes, the server response may include additional properties that are not yet available in this library's types. You can access them using the model's `_additionalProperties` method: ```java +import com.moderntreasury.api.core.JsonValue; + JsonValue secret = asyncResponse._additionalProperties().get("secret_field"); ``` @@ -201,17 +213,18 @@ JsonValue secret = asyncResponse._additionalProperties().get("secret_field"); ## Pagination -For methods that return a paginated list of results, this library provides convenient ways access -the results either one page at a time, or item-by-item across all pages. +For methods that return a paginated list of results, this library provides convenient ways access the results either one page at a time, or item-by-item across all pages. ### Auto-pagination -To iterate through all results across all pages, you can use `autoPager`, -which automatically handles fetching more pages for you: +To iterate through all results across all pages, you can use `autoPager`, which automatically handles fetching more pages for you: ### Synchronous ```java +import com.moderntreasury.api.models.Counterparty; +import com.moderntreasury.api.models.CounterpartyListPage; + // As an Iterable: CounterpartyListPage page = client.counterparties().list(params); for (Counterparty counterparty : page.autoPager()) { @@ -234,12 +247,12 @@ asyncClient.counterparties().list(params).autoPager() ### Manual pagination -If none of the above helpers meet your needs, you can also manually request pages one-by-one. -A page of results has a `data()` method to fetch the list of objects, as well as top-level -`response` and other methods to fetch top-level data about the page. It also has methods -`hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination. +If none of the above helpers meet your needs, you can also manually request pages one-by-one. A page of results has a `data()` method to fetch the list of objects, as well as top-level `response` and other methods to fetch top-level data about the page. It also has methods `hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination. ```java +import com.moderntreasury.api.models.Counterparty; +import com.moderntreasury.api.models.CounterpartyListPage; + CounterpartyListPage page = client.counterparties().list(params); while (page != null) { for (Counterparty counterparty : page.items()) { @@ -258,31 +271,33 @@ This library throws exceptions in a single hierarchy for easy handling: - **`ModernTreasuryException`** - Base exception for all exceptions - - **`ModernTreasuryServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server. +- **`ModernTreasuryServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server. - | 400 | BadRequestException | - | ------ | ----------------------------- | - | 401 | AuthenticationException | - | 403 | PermissionDeniedException | - | 404 | NotFoundException | - | 422 | UnprocessableEntityException | - | 429 | RateLimitException | - | 5xx | InternalServerException | - | others | UnexpectedStatusCodeException | + | 400 | BadRequestException | + | ------ | ----------------------------- | + | 401 | AuthenticationException | + | 403 | PermissionDeniedException | + | 404 | NotFoundException | + | 422 | UnprocessableEntityException | + | 429 | RateLimitException | + | 5xx | InternalServerException | + | others | UnexpectedStatusCodeException | - - **`ModernTreasuryIoException`** - I/O networking errors - - **`ModernTreasuryInvalidDataException`** - any other exceptions on the client side, e.g.: - - We failed to serialize the request body - - We failed to parse the response body (has access to response code and body) +- **`ModernTreasuryIoException`** - I/O networking errors +- **`ModernTreasuryInvalidDataException`** - any other exceptions on the client side, e.g.: + - We failed to serialize the request body + - We failed to parse the response body (has access to response code and body) ## Network options ### Retries -Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. -You can provide a `maxRetries` on the client builder to configure this: +Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. You can provide a `maxRetries` on the client builder to configure this: ```java +import com.moderntreasury.api.client.ModernTreasuryClient; +import com.moderntreasury.api.client.okhttp.ModernTreasuryOkHttpClient; + ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder() .fromEnv() .maxRetries(4) @@ -294,6 +309,10 @@ ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder() Requests time out after 1 minute by default. You can configure this on the client builder: ```java +import com.moderntreasury.api.client.ModernTreasuryClient; +import com.moderntreasury.api.client.okhttp.ModernTreasuryOkHttpClient; +import java.time.Duration; + ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder() .fromEnv() .timeout(Duration.ofSeconds(30)) @@ -305,24 +324,24 @@ ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder() Requests can be routed through a proxy. You can configure this on the client builder: ```java +import com.moderntreasury.api.client.ModernTreasuryClient; +import com.moderntreasury.api.client.okhttp.ModernTreasuryOkHttpClient; +import java.net.InetSocketAddress; +import java.net.Proxy; + ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder() .fromEnv() - .proxy(new Proxy( - Type.HTTP, - new InetSocketAddress("proxy.com", 8080) - )) + .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("example.com", 8080))) .build(); ``` ## Making custom/undocumented requests -This library is typed for convenient access to the documented API. If you need to access undocumented -params or response properties, the library can still be used. +This library is typed for convenient access to the documented API. If you need to access undocumented params or response properties, the library can still be used. ### Undocumented request params -To make requests using undocumented parameters, you can provide or override parameters on the params object -while building it. +To make requests using undocumented parameters, you can provide or override parameters on the params object while building it. ```kotlin FooCreateParams address = FooCreateParams.builder() @@ -333,10 +352,7 @@ FooCreateParams address = FooCreateParams.builder() ### Undocumented response properties -To access undocumented response properties, you can use `res._additionalProperties()` on a response object to -get a map of untyped fields of type `Map`. You can then access fields like -`._additionalProperties().get("secret_prop").asString()` or use other helpers defined on the `JsonValue` class -to extract it to a desired type. +To access undocumented response properties, you can use `res._additionalProperties()` on a response object to get a map of untyped fields of type `Map`. You can then access fields like `._additionalProperties().get("secret_prop").asString()` or use other helpers defined on the `JsonValue` class to extract it to a desired type. ## Logging