# (DD09) Business Logic — CurrencyRateAPI.getCurrencyCode() [10 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.github.blaxk3.api.CurrencyRateAPI` |
| Layer | Utility / API integration helper |
| Module | `api` (Package: `com.github.blaxk3.api`) |

## 1. Role

### CurrencyRateAPI.getCurrencyCode()

This method retrieves the list of available currency codes from an external exchange-rate service and returns them as a `String[]`. Business-wise, it is a catalog lookup operation: the application uses it to discover which currencies are supported by the remote rate provider before presenting or using them in the UI. The method always targets the USD-based latest-rate endpoint, then extracts the `conversion_rates` object from the JSON payload and converts its property names into an array. If the response is missing, malformed, or does not contain any currency entries, the method returns `null` rather than an empty array, which signals that the currency catalog could not be resolved.

The method implements a simple routing-and-extraction pattern: it delegates the HTTP request and JSON parsing to `getJsonObject(URL)`, then performs defensive checks on the response structure. Its role in the larger system is that of a shared data provider used by the UI layer to populate currency-related controls or downstream conversion logic. There are no business branches by service type inside this method; instead, the only decision points are response validation branches that separate successful catalog retrieval from failure or empty-data conditions.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["getCurrencyCode()"]
    BUILD_URL["Build URL: getURL() + /latest/ + USD"]
    CALL_JSON["Call getJsonObject(URL)"]
    JSON_NULL{"JSON object is null?"}
    HAS_RATES{"Has conversion_rates?"}
    GET_CODE["Read conversion_rates object"]
    IS_EMPTY{"Currency code set is empty?"}
    RETURN_CODES["Return keySet as String[]"]
    RETURN_NULL["Return null"]

    START --> BUILD_URL
    BUILD_URL --> CALL_JSON
    CALL_JSON --> JSON_NULL
    JSON_NULL -- "Yes" --> RETURN_NULL
    JSON_NULL -- "No" --> HAS_RATES
    HAS_RATES -- "No" --> RETURN_NULL
    HAS_RATES -- "Yes" --> GET_CODE
    GET_CODE --> IS_EMPTY
    IS_EMPTY -- "Yes" --> RETURN_NULL
    IS_EMPTY -- "No" --> RETURN_CODES
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| - | (none) | - | - |

This method does not accept input parameters. It depends on instance methods and external configuration state instead: `getURL()` constructs the remote service endpoint using the configured API key, and `getJsonObject(URL)` performs the outbound HTTP request and parses the response payload.

## 4. CRUD Operations / Called Services

### Pre-computed evidence from code analysis graph:

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `CurrencyRateAPI.getJsonObject` | CurrencyRateAPI | - | Calls `getJsonObject` in `CurrencyRateAPI` |
| R | `CurrencyRateAPI.getURL` | CurrencyRateAPI | - | Calls `getURL` in `CurrencyRateAPI` |

Analyze all method calls within this method and classify each as a CRUD operation.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `getURL` | CurrencyRateAPI | External exchange-rate API endpoint | Resolves the base service URL that includes the configured API key |
| R | `getJsonObject` | CurrencyRateAPI | External exchange-rate API response JSON | Performs the HTTP GET request and parses the remote response into a JSON object |
| R | `has` | JsonObject | External response JSON | Checks whether the response contains the `conversion_rates` field |
| R | `getAsJsonObject` | JsonObject | External response JSON | Extracts the nested currency-rate map from the response |
| R | `keySet` | JsonObject | External response JSON | Reads available currency-code keys from the conversion-rate map |
| R | `toArray` | Collection / Array conversion | In-memory result array | Converts the discovered currency-code set into the returned `String[]` |

## 5. Dependency Trace

### Pre-computed evidence from code analysis graph:

No screen/batch entry points found within 8 hops. Direct callers found: 1 methods.
Terminal operations from this method: `getJsonObject` [R], `getURL` [R]

Trace who calls this method and what this method ultimately calls.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | `UI` | `UI.getCurrencyCode()` -> `CurrencyRateAPI.getCurrencyCode()` | `getJsonObject [R] External exchange-rate API response JSON` |

## 6. Per-Branch Detail Blocks

**Block 1** — Sequence / linear execution `(L61-L70)`

> Retrieves the supported currency-code catalog from the remote exchange-rate API and converts it into an array for the caller.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JsonObject jsonObject = getJsonObject(new java.net.URI(getURL() + "/latest/" + "USD").toURL());` |
| 2 | CALL | `getURL()` |
| 3 | CALL | `getJsonObject(URL)` |

**Block 2** — IF `(jsonObject != null && jsonObject.has("conversion_rates"))` `(L62)`

> Validates that the remote response exists and includes the currency-rate collection.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `jsonObject.has("conversion_rates")` |
| 2 | RETURN | `return null;` when the response is missing or does not contain rate data |

**Block 2.1** — IF `(code != null && !code.keySet().isEmpty())` `(L63-L64)`

> Confirms that the extracted currency map is not empty before exposing its keys to the caller.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JsonObject code = jsonObject.getAsJsonObject("conversion_rates");` |
| 2 | EXEC | `code.keySet()` |
| 3 | RETURN | `return code.keySet().toArray(new String[0]);` |

**Block 2.2** — ELSE `(code == null || code.keySet().isEmpty())` `(L63-L64)`

> Handles the case where the response structure is present but no currency codes can be extracted.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return null;` |

**Block 3** — ELSE `(jsonObject == null || !jsonObject.has("conversion_rates"))` `(L62)`

> Handles remote request failure, unexpected payload structure, or missing rate data.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return null;` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `CurrencyRateAPI` | Class | API integration helper that communicates with the external exchange-rate provider |
| `getCurrencyCode` | Method | Retrieves the supported currency-code list from the latest exchange-rate response |
| `getURL` | Method | Builds the base URL for the exchange-rate service using the configured API key |
| `getJsonObject` | Method | Executes the HTTP GET request and parses the response body into JSON |
| `config.properties` | Configuration file | Local properties file that stores the external API key |
| `API_KEY` | Configuration property | Credential used to access the exchange-rate API |
| `conversion_rates` | JSON field | Map of currency codes to exchange-rate values returned by the provider |
| `USD` | Currency code | Base currency used in the latest-rate API request |
| `String[]` | Data type | Array of currency-code identifiers returned to the caller |
| `conversion_result` | JSON field | Conversion amount returned by the provider in related conversion operations |
| `HttpURLConnection` | Technical component | Java HTTP client used to call the external service |
| `JsonObject` | Technical component | Parsed JSON response container |
| `JsonParser` | Technical component | Library parser that converts the HTTP response stream into JSON |
| `MalformedURLException` | Technical exception | Raised if the constructed URL is invalid |
| `URISyntaxException` | Technical exception | Raised if the URI used to build the API request is invalid |
| `exchange-rate API` | Business term | External service that publishes foreign-exchange rate data |
| `currency code` | Business term | ISO-like identifier for a currency such as USD, EUR, or JPY |
| `latest rate endpoint` | Business term | API endpoint that returns the most recent exchange-rate snapshot |