Skip to content

Commit

Permalink
chore(docs): update readme (#289)
Browse files Browse the repository at this point in the history
  • Loading branch information
@stainless-app
stainless-app[bot] authored Dec 19, 2024
1 parent f9fa926 commit 01c546c
Showing 1 changed file with 64 additions and 48 deletions.
112 changes: 64 additions & 48 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
Expand All @@ -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()) {
Expand All @@ -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"))
Expand Down Expand Up @@ -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"))
Expand All @@ -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()) {
Expand All @@ -194,24 +204,27 @@ 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");
```

---

## 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()) {
Expand All @@ -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()) {
Expand All @@ -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)
Expand All @@ -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))
Expand All @@ -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()
Expand All @@ -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<String, JsonValue>`. 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<String, JsonValue>`. 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

Expand Down

0 comments on commit 01c546c

Please sign in to comment.