SDK architecture

The SDK separates public API ergonomics from transport behavior.

OkatanaClient
  ├── OrganizationsApi
  ├── ProjectsApi
  ├── BoardsApi
  ├── TicketsApi
  └── DocumentsApi
          │
          ▼
  OkatanaHttpTransport
          │
          ├── URL normalization and path escaping
          ├── bearer/Accept/User-Agent headers
          ├── JSON serialization/deserialization
          ├── timeouts and cancellation
          ├── safe-read retry policy
          ├── error mapping
          └── pagination URL boundary checks
                  │
                  ▼
               HttpClient

Request types validate OpenAPI limits and convert C# properties into the API's snake_case payload. Response models use JsonPropertyName attributes and JsonExtensionData, which allows typed access to stable fields while preserving unknown additions.

The main client owns its HttpClient only when it creates the HTTP stack itself. If an application injects a caller-managed HttpClient or resolves the SDK as a typed client through IHttpClientFactory, disposing the SDK does not dispose that external client.

The direct-client constructor uses a long-lived SocketsHttpHandler with a finite pooled connection lifetime. The dependency-injection constructor works with IHttpClientFactory, which manages handler lifetime on behalf of the application.