Skip to content

sync.md

Latest commit

 

History

History
185 lines (139 loc) · 3.26 KB

sync.md

File metadata and controls

185 lines (139 loc) · 3.26 KB

Sync Client

The Ark client executes requests synchronously - blocking until the response is received.

Installation

<dependency>
    <groupId>xyz.juandiii</groupId>
    <artifactId>ark-core</artifactId>
</dependency>
<dependency>
    <groupId>xyz.juandiii</groupId>
    <artifactId>ark-jackson</artifactId>
</dependency>
<dependency>
    <groupId>xyz.juandiii</groupId>
    <artifactId>ark-transport-jdk</artifactId>
</dependency>

Or use the Spring Boot starter:

<dependency>
    <groupId>xyz.juandiii</groupId>
    <artifactId>ark-spring-boot-starter</artifactId>
</dependency>

Transport

  • Interface: HttpTransport - returns RawResponse
  • Implementation: ArkJdkHttpTransport - backed by Java's HttpClient

Building the Client

Manual

Ark client = ArkClient.builder()
    .serializer(new JacksonSerializer(new ObjectMapper()))
    .transport(new ArkJdkHttpTransport(HttpClient.newBuilder().build()))
    .baseUrl("https://api.example.com")
    .build();

With Spring Boot Starter

@Configuration
public class HttpClientsConfig {

    @Bean
    public Ark apiClient(ArkClient.Builder builder) {
        return builder
            .baseUrl("https://api.example.com")
            .build();
    }
}

Making Requests

GET

User user = client.get("/users/1")
    .accept(MediaType.APPLICATION_JSON)
    .retrieve()
    .body(User.class);

GET with generics

List<User> users = client.get("/users")
    .queryParam("page", "1")
    .queryParam("size", "20")
    .retrieve()
    .body(new TypeRef<List<User>>() {});

POST

User created = client.post("/users")
    .contentType(MediaType.APPLICATION_JSON)
    .body(new User("Juan", "juan@example.com"))
    .retrieve()
    .body(User.class);

PUT

User updated = client.put("/users/1")
    .contentType(MediaType.APPLICATION_JSON)
    .body(updatedUser)
    .retrieve()
    .body(User.class);

DELETE

client.delete("/users/1")
    .retrieve()
    .toBodilessEntity();

Full Response

ArkResponse<User> response = client.get("/users/1")
    .retrieve()
    .toEntity(User.class);

int status = response.statusCode();
User body = response.body();
boolean ok = response.isSuccessful();

Per-Request Timeout

User user = client.get("/slow-endpoint")
    .timeout(Duration.ofSeconds(60))
    .retrieve()
    .body(User.class);

Raw String Response

String html = client.get("/health")
    .retrieve()
    .body(String.class);

Logging

See Logging for full details. Quick setup:

ark.logging.level=BODY

Levels: NONE, BASIC, HEADERS, BODY.

Error Handling

See Error Handling for the full exception hierarchy and examples per execution model.

try {
    User user = client.get("/users/1").retrieve().body(User.class);
} catch (NotFoundException e) {
    // 404
} catch (ServerException e) {
    // 5xx
} catch (TimeoutException e) {
    // request timed out
}

Related