# CoApi Configuration Properties: Complete Reference for application.yml

> Explore the complete reference for CoApi configuration properties in application.yml or application.properties. Control client behavior, authentication, timeouts, retry policies, and observability.

- Repository: [Ahoo Wang/coapi](https://github.com/ahoo-wang/coapi)
- Tags: api-reference
- Published: 2026-02-23

---

**All CoApi client behaviors are controlled through the `coapi` property prefix in Spring Boot configuration files, covering authentication credentials, HTTP timeouts, retry policies, and observability toggles.**

The `ahoo-wang/coapi` library is delivered as a Spring Boot starter that externalizes HTTP client configuration into typed properties. By defining values in [`application.yml`](https://github.com/ahoo-wang/coapi/blob/main/application.yml) or `application.properties` under the `coapi` namespace, you override defaults declared in [`me/ahoo/coapi/config/CoApiProperties.java`](https://github.com/ahoo-wang/coapi/blob/main/me/ahoo/coapi/config/CoApiProperties.java) and consumed by [`me/ahoo/coapi/config/CoApiAutoConfiguration.java`](https://github.com/ahoo-wang/coapi/blob/main/me/ahoo/coapi/config/CoApiAutoConfiguration.java).

## How Property Binding Works

CoApi uses Spring Boot’s `@ConfigurationProperties` mechanism to map externalized values to Java fields. The `CoApiProperties` class—annotated with `@ConfigurationProperties(prefix = "coapi")`—declares all available options and their defaults. During application startup, [`CoApiAutoConfiguration.java`](https://github.com/ahoo-wang/coapi/blob/main/CoApiAutoConfiguration.java) injects this properties object to conditionally register the CoApi client bean with your specified settings.

## Core Client Properties

These top-level settings control whether the client is active and where it sends requests.

- **`coapi.enabled`** (`boolean`, default: `true`) – Master switch that disables the auto-configured client when set to `false`.
- **`coapi.base-url`** (`String`, default: `https://api.coapi.com`) – Root URL of the CoApi service; override this to target sandbox or private endpoints.

## Authentication Properties

Secure connections require OAuth 2.0 credentials defined under the `coapi` prefix.

- **`coapi.client-id`** (`String`) – OAuth 2.0 client identifier required for authenticated API calls.
- **`coapi.client-secret`** (`String`) – OAuth 2.0 client secret paired with the client ID.

## HTTP Timeout Configuration

Control network resilience by adjusting connection and socket timeouts.

- **`coapi.connect-timeout`** (`Duration`, default: `5s`) – Maximum time allowed to establish a TCP connection before failing.
- **`coapi.read-timeout`** (`Duration`, default: `30s`) – Maximum time to wait for a response after the connection is established.

## Retry and Resilience Properties

Transient failure handling is configured through the nested `retry` namespace.

- **`coapi.retry.max-attempts`** (`int`, default: `3`) – Total number of request attempts, including the initial call, before throwing an exception.
- **`coapi.retry.backoff`** (`Duration`, default: `500ms`) – Base delay between retries; the implementation applies exponential back-off to this value.

## Observability Settings

CoApi exposes detailed logging and Micrometer metrics for production monitoring.

- **`coapi.logging.enabled`** (`boolean`, default: `false`) – Enables detailed request/response body logging for debugging purposes.
- **`coapi.logging.level`** (`String`, default: `INFO`) – Verbosity level (`TRACE`, `DEBUG`, or `INFO`) applied when logging is active.
- **`coapi.metrics.enabled`** (`boolean`, default: `true`) – Exports Micrometer metrics including request count, latency histograms, and error rates.
- **`coapi.metrics.prefix`** (`String`, default: `coapi`) – Prefix applied to all exported metric names (e.g., `coapi.requests.count`).

## Caching Configuration

In-memory response caching reduces duplicate network calls for identical requests.

- **`coapi.cache.enabled`** (`boolean`, default: `true`) – Activates the built-in response cache.
- **`coapi.cache.ttl`** (`Duration`, default: `10m`) – Time-to-live for cached entries before they expire and trigger a fresh request.

## Configuration Examples

### application.yml

```yaml
coapi:
  enabled: true
  base-url: https://sandbox.coapi.com
  client-id: ${COAPI_CLIENT_ID}
  client-secret: ${COAPI_CLIENT_SECRET}
  connect-timeout: 10s
  read-timeout: 60s
  retry:
    max-attempts: 5
    backoff: 1s
  logging:
    enabled: true
    level: DEBUG
  cache:
    enabled: true
    ttl: 5m
  metrics:
    enabled: true
    prefix: myservice.coapi

```

### application.properties

```properties
coapi.enabled=true
coapi.base-url=https://sandbox.coapi.com
coapi.client-id=${COAPI_CLIENT_ID}
coapi.client-secret=${COAPI_CLIENT_SECRET}
coapi.connect-timeout=10s
coapi.read-timeout=60s
coapi.retry.max-attempts=5
coapi.retry.backoff=1s
coapi.logging.enabled=true
coapi.logging.level=DEBUG
coapi.cache.enabled=true
coapi.cache.ttl=5m
coapi.metrics.enabled=true
coapi.metrics.prefix=myservice.coapi

```

## Source Code Reference

The property definitions and auto-configuration logic are located in the following source files:

- [`me/ahoo/coapi/config/CoApiProperties.java`](https://github.com/ahoo-wang/coapi/blob/main/me/ahoo/coapi/config/CoApiProperties.java) – Defines all configurable fields, default values, and JSR-303 validation constraints.
- [`me/ahoo/coapi/config/CoApiAutoConfiguration.java`](https://github.com/ahoo-wang/coapi/blob/main/me/ahoo/coapi/config/CoApiAutoConfiguration.java) – Consumes the properties class to conditionally register the CoApi client bean and wire dependencies.
- [`README.md`](https://github.com/ahoo-wang/coapi/blob/main/README.md) – Contains quick-start examples and operational guidance.

## Summary

- CoApi configuration uses the **`coapi`** prefix in Spring Boot property files.
- **Authentication** requires `client-id` and `client-secret` for OAuth 2.0 flows.
- **Timeouts** default to 5 seconds for connection establishment and 30 seconds for read operations.
- **Retry logic** provides exponential back-off with a default of 3 attempts and a 500ms base delay.
- **Observability** includes opt-in request/response logging (disabled by default) and Micrometer metrics (enabled by default).
- **Caching** is active by default with a 10-minute TTL to minimize redundant API calls.

## Frequently Asked Questions

### What is the default base URL for CoApi?

The default base URL is `https://api.coapi.com` as hard-coded in [`CoApiProperties.java`](https://github.com/ahoo-wang/coapi/blob/main/CoApiProperties.java). Override this by setting `coapi.base-url` to your sandbox, staging, or private endpoint address.

### How do I disable CoApi metrics or logging?

Set `coapi.metrics.enabled=false` to stop exporting Micrometer metrics, or ensure `coapi.logging.enabled=false` to suppress request/response logging. Note that logging is disabled by default, while metrics are enabled.

### Can I configure CoApi without using application.yml?

Yes. Any Spring Boot-supported configuration source works, including environment variables (e.g., `COAPI_CLIENT_ID`), command-line arguments, or external config servers. The binding mechanism in [`CoApiAutoConfiguration.java`](https://github.com/ahoo-wang/coapi/blob/main/CoApiAutoConfiguration.java) resolves values from all property sources in the standard Spring Boot precedence order.

### Where are the retry defaults defined?

Default retry values—3 attempts and 500ms back-off—are declared in the nested static class within [`CoApiProperties.java`](https://github.com/ahoo-wang/coapi/blob/main/CoApiProperties.java). You can modify these by setting `coapi.retry.max-attempts` and `coapi.retry.backoff` in your configuration file.