Skip to content

Okatana Java SDK

Okatana Java 21 SDK for the Okatana External API v1. Designed for server-to-server integrations, scheduled jobs, CI/CD automation, operational tooling, and application backends.

Explicit Okatana host required

The client requires an explicit API deployment URL. https://okatana.newfoundcodes.com is the documentation site, not a default API host.

SDK features

Provides five service objects: organizations, projects, boards, tickets, and documents. Features include schema-based request validation, immutable/fluent request objects, native JDK HttpClient transport, normalized bearer authentication, Jackson JSON decoding, pagination support, typed models, and status-specific exceptions.

Service methods map directly to routes, return typed models, and preserve unknown response fields via DynamicResource.

Typical client lifecycle

import com.newfoundcodes.okatana.OkatanaClient;

var client = OkatanaClient.builder()
    .baseUrl(System.getenv("OKATANA_URL"))
    .apiKey(System.getenv("OKATANA_API_KEY"))
    .build();

var organization = client.organizations().get(System.getenv("OKATANA_ORGANIZATION_ID"));

baseUrl normalizes to /api/v1. Origin and full API base are both valid:

https://okatana.internal.example      -> https://okatana.internal.example/api/v1
https://okatana.internal.example/api/v1 -> unchanged

Design principles

  1. Explicit deployment configuration. Requires deployment URL before sending tokens.
  2. One method per endpoint.
  3. Predictable transport. Uses the native JDK HttpClient; accepts custom configured client instances.
  4. Conservative writes. Limits automatic retries to safe reads.
  5. Schema-aware. Validates documented constraints; preserves unknown fields in responses.
  6. Raw requests. The low-level client supports unmapped v1 routes.

Documentation

See Installation, Configuration, and Quickstart. For production integration behavior, read Errors, Retries and rate limits, and Security.