Build a Praxa backend with Java and Spring

​

Prerequisites

• a trusted server runtime and application authentication boundary;
• a disposable personal workspace Praxa key with only the tutorial’s required scopes;
• synthetic input plus a persisted application request ID for replay tests;
• a fake upstream for unit tests and a non-production environment for canaries;
• an acceptance assertion that proves the Spring boundary admits one task with typed readback and a fake-client regression test.

​

1. Configure the client

package example;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
import java.util.Map;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.RestClientResponseException;

public final class PraxaClient {
  public record Run(String run_id, String status) {}

  private final RestClient client;

  public PraxaClient(RestClient.Builder builder, String apiKey) {
    this.client = builder
        .baseUrl("https://api.praxa.io")
        .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + apiKey)
        .build();
  }

  public Run submitTask(String userId, String logicalRequestId, String input) {
    if (input == null || input.isBlank() || input.length() > 16_000) {
      throw new IllegalArgumentException("Invalid task input");
    }

    String key = "spring:" + sha256(userId + "\0" + logicalRequestId);
    Map<String, Object> body = Map.of(
        "apiVersion", "v1",
        "requestId", key,
        "mode", "task",
        "task", Map.of("input", input),
        "idempotencyKey", key
    );

    return client.post()
        .uri("/v1/execute")
        .contentType(MediaType.APPLICATION_JSON)
        .header("Idempotency-Key", key)
        .body(body)
        .retrieve()
        .body(Run.class);
  }

  private static String sha256(String value) {
    try {
      byte[] digest = MessageDigest.getInstance("SHA-256")
          .digest(value.getBytes(StandardCharsets.UTF_8));
      return HexFormat.of().formatHex(digest);
    } catch (NoSuchAlgorithmException error) {
      throw new IllegalStateException("SHA-256 unavailable", error);
    }
  }
}

​

2. Add an application controller

try {
  return ResponseEntity.accepted()
      .cacheControl(CacheControl.noStore())
      .body(praxa.submitTask(principal.getName(), body.requestId(), body.task()));
} catch (RestClientResponseException error) {
  return ResponseEntity.status(error.getStatusCode())
      .cacheControl(CacheControl.noStore())
      .body(Map.of("error", "Praxa request failed"));
}

​

3. Test the outbound contract

• exact /v1/execute POST;
• bearer and idempotency headers;
• stable key for the same principal/request pair;
• different key for a different principal;
• no upstream call for invalid input;
• safe mapping for 401, 403, 409, and 429;
• no authorization value in controller responses or logs.

./mvnw test
# or
./gradlew test

​

4. Verify live behavior

​

Troubleshooting

​

Best practices

• Reuse the thread-safe RestClient.
• Configure connect and read timeouts on the underlying request factory.
• Keep authentication and tenant derivation in the controller/service boundary.
• Use records or DTOs instead of unbounded maps in production.
• Preserve key/body digests for reconciliation.
• Prefer RestClient over deprecated RestTemplate on current Spring.

​

Optimize for production

• Reuse one configured HTTP or SDK client per process and bound concurrent upstream work.
• Prefer durable admission plus asynchronous readback over holding application requests open.
• Cache only non-sensitive, tenant-scoped reads within their documented freshness window.
• Measure p50/p95 latency, admission-to-terminal time, retries, conflicts, and connection reuse before tuning.

​

Cleanup and next steps

1. Revoke the disposable Praxa key and require a later request to fail.
2. Remove synthetic application records and any temporary environment files.
3. Cancel or archive unresolved test runs according to the application policy.
4. Retain only redacted request, run, and verification identifiers needed for the test record.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?