CoApi Configuration Properties: Complete Reference for application.yml

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 or application.properties under the coapi namespace, you override defaults declared in me/ahoo/coapi/config/CoApiProperties.java and consumed by 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 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

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

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 – Defines all configurable fields, default values, and JSR-303 validation constraints.
• me/ahoo/coapi/config/CoApiAutoConfiguration.java – Consumes the properties class to conditionally register the CoApi client bean and wire dependencies.
• 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. 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 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. You can modify these by setting coapi.retry.max-attempts and coapi.retry.backoff in your configuration file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}