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

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

## 1. Role

### CurrencyRateAPI.getCurrencyCode()

This method retrieves the list of supported foreign currency codes from an external exchange-rate service and returns them as a `String[]`. In business terms, it is a discovery function: it asks the upstream currency API for the latest USD-based rate payload and extracts the available currency identifiers from the `conversion_rates` object. This supports downstream screens or services that need a dynamic currency master list instead of a hard-coded set of codes.

The method follows a simple request-and-transform pattern. It first builds the target endpoint URL, delegates HTTP/JSON retrieval to `getJsonObject(...)`, and then inspects the returned payload for the `conversion_rates` section. If that section exists and contains at least one code, the method converts the key set into a string array and returns it. If the payload is absent, malformed, or contains no codes, the method returns `null` rather than an empty array, which means callers must handle the no-data case explicitly.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["getCurrencyCode()"])
    CALL_GETURL(["Call getURL()"])
    CALL_GETJSON(["Call getJsonObject(URI.toURL())"])
    DECIDE_HAS(["jsonObject != null and has conversion_rates?"])
    GET_CODES(["Get conversion_rates JsonObject"])
    DECIDE_EMPTY(["code != null and keySet not empty?"])
    RETURN_CODES(["Return code.keySet() as String[]"])
    RETURN_NULL(["Return null"])
    START --> CALL_GETURL
    CALL_GETURL --> CALL_GETJSON
    CALL_GETJSON --> DECIDE_HAS
    DECIDE_HAS -->|Yes| GET_CODES
    DECIDE_HAS -->|No| RETURN_NULL
    GET_CODES --> DECIDE_EMPTY
    DECIDE_EMPTY -->|Yes| RETURN_CODES
    DECIDE_EMPTY -->|No| RETURN_NULL
```

The method has one external service call and two validation gates. The first gate checks whether the HTTP response produced a JSON object that contains the `conversion_rates` node. The second gate checks whether that node can supply at least one currency code. Only the positive path returns a populated `String[]`; all negative paths terminate with `null`.

## 3. Parameter Analysis

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

External state read by this method:
- Instance methods `getURL()` and `getJsonObject(...)` from the same class.
- Remote exchange-rate payload returned by the upstream API.

## 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 endpoint URL | Resolves the base service URL used to reach the currency API |
| R | `getJsonObject(URL)` | CurrencyRateAPI | External exchange-rate response payload | Retrieves and parses the latest USD rate JSON document |
| R | `jsonObject.has("conversion_rates")` | - | External exchange-rate response payload | Checks whether the response contains the currency-code map |
| R | `jsonObject.getAsJsonObject("conversion_rates")` | - | External exchange-rate response payload | Reads the currency-code object from the JSON response |
| R | `code.keySet()` | - | External exchange-rate response payload | Enumerates the available currency codes returned by the service |

## 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 -> CurrencyRateAPI.getCurrencyCode()` | `getJsonObject [R] External exchange-rate response payload` |

## 6. Per-Branch Detail Blocks

**Block 1** — [CALL] (initialize request URL and fetch JSON payload) (L61)

| # | Type | Code |
|---|------|------|
| 1 | CALL | `getURL()` |
| 2 | CALL | `getJsonObject(new java.net.URI(getURL() + "/latest/" + "USD").toURL())` |

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

> Validates that the upstream service returned a usable response containing the currency-code map.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `jsonObject.has("conversion_rates")` |

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

> Confirms the extracted currency-code object contains at least one supported currency.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JsonObject code = jsonObject.getAsJsonObject("conversion_rates");` |
| 2 | EXEC | `code.keySet()` |

**Block 2.1.1** — [RETURN] `(positive path)` (L65)

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return code.keySet().toArray(new String[0]);` |

**Block 2.2** — [RETURN] `(no conversion rates or empty set)` (L70)

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `conversion_rates` | JSON field | Map of supported currency codes to their exchange rates in the upstream API response |
| `getURL` | Method | Helper that resolves the base endpoint URL for the external currency service |
| `getJsonObject` | Method | Helper that performs the HTTP request and parses the response into a JSON object |
| USD | Business term | United States Dollar, used as the base currency for the latest-rate lookup |
| currency code | Business term | Short identifier for a tradable currency such as USD, EUR, or JPY |
| exchange rate service | External system | Remote API that publishes current foreign exchange conversion data |
| key set | Technical term | The collection of field names in the `conversion_rates` JSON object; each key is a supported currency code |