Architecture

The SDK separates public domain services from transport and parsing concerns.

Application
   |
   v
OkatanaClient
   |
   +-- OrganizationsApi
   +-- ProjectsApi
   +-- BoardsApi
   +-- TicketsApi
   +-- DocumentsApi
            |
            v
      OkatanaTransport
            |
            +-- URL normalization and confinement
            +-- bearer authentication
            +-- JSON serialization
            +-- timeout policy
            +-- retry policy
            +-- error mapping
            +-- observability
            |
            v
     java.net.http.HttpClient

ResponseParser unwraps top-level data, converts arrays, and maps nested Laravel paginator objects.

Design goals

The design favors explicit behavior over generated-client magic. A deployment URL is mandatory. Write retries are disabled by default. PATCH requests record which setters were called. Unknown response fields are retained. Absolute links are checked before credentials are sent.

Dependency boundary

HTTP transport uses Java 21's standard HttpClient. JSON uses Jackson. The SDK does not require Spring, Jakarta REST, Retrofit, OkHttp, or a particular dependency-injection container.