contentstack-java-cda.mdc

---
description: Contentstack CDA patterns – Stack/Config, HTTP, retry, callbacks, Content Delivery API
globs: "src/main/java/com/contentstack/sdk/**/*.java"
---

# Contentstack Java CDA – SDK Rules

Apply when editing the SDK core (`com.contentstack.sdk`). Keep behavior aligned with the [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/).

## Stack and Config

- **Entry point:** `Contentstack.stack(apiKey, deliveryToken, environment)` returns a `Stack`. Use `Config` for optional settings.
- **Default host:** `cdn.contentstack.io`; **API version:** `v3` (see `Config`).
- **Config options:** host, version, scheme, region (`ContentstackRegion`), branch, live preview, proxy, connection pool, **RetryOptions**, early access, plugins. Set these via `Config` before building the stack.
- **Region/branch:** Support `Config.setRegion()` and `Config.setBranch()` for regional and branch-specific delivery.

## HTTP layer

- **Requests** go through **`CSHttpConnection`** and **`APIService`** (Retrofit). Do not bypass this for CDA calls.
- **Headers:** Use the same headers and User-Agent as the rest of the SDK (see `Constants` and request setup in `CSHttpConnection`).
- **Errors:** Map API errors to the SDK **`Error`** class (errorMessage, errorCode, errDetails) and pass to **`ResultCallBack`** or equivalent callback.

## Retry and resilience

- **RetryOptions:** Configurable retry limit, delay, backoff strategy (e.g. exponential), and retryable status codes (e.g. 408, 429, 502, 503, 504). Defaults are in `RetryOptions`.
- **RetryInterceptor:** Uses `RetryOptions` to retry failed HTTP requests. Keep retry behavior consistent when changing the HTTP client or interceptors.

## Callbacks and async

- Use existing callback types (e.g. **`ResultCallBack`**, **`EntryResultCallBack`**, **`QueryResultsCallBack`**) for async results. Do not introduce incompatible callback signatures without considering backward compatibility.
- Pass **`Error`** and response data through the same callback patterns used elsewhere in the SDK.

## CDA concepts

- **Entry,** **Query,** **Asset,** **Content Type,** **Sync,** **Taxonomy** – follow existing class and method names and the CDA API semantics (e.g. query params, response parsing). When adding new CDA features, align with the official Content Delivery API documentation.