---

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

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

## 1. Role

### CurrencyRateAPI.getCurrencyCode()

This method retrieves the list of supported currency codes from an external currency-rate API by requesting the USD latest-rate endpoint and reading the `conversion_rates` section of the JSON response. Its business purpose is to provide the application with the set of available foreign currency identifiers that can be used elsewhere in the user interface or conversion flow. The method acts as a lightweight data-discovery utility rather than a transformation engine: it does not calculate rates itself, but exposes the API’s supported currency universe as a string array.

The method follows a simple routing-and-extraction pattern. First, it builds the external URL using the base URL returned by `getURL()`, then it delegates the HTTP/JSON fetch to `getJsonObject(...)`. After the response is received, it validates that the payload contains the `conversion_rates` object and that the extracted key set is not empty. If both checks pass, it returns the currency code list as a `String[]`; otherwise, it returns `null` to indicate that the currency catalog could not be resolved from the upstream service.

This method is typically used as a shared lookup function by higher layers, such as the UI, that need to populate currency selection controls or validate supported currencies before conversion. In that sense, it is a read-only integration endpoint that supports consumer-facing display logic and downstream conversion requests.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["getCurrencyCode()"]
    CALL_GET_URL["Call getURL()"]
    BUILD_URL["Build endpoint URL - /latest/USD"]
    CALL_GET_JSON["Call getJsonObject(URI.toURL())"]
    DECISION_JSON["jsonObject != null and has conversion_rates?"]
    GET_CODE["Extract conversion_rates as JsonObject"]
    DECISION_KEYS["code != null and keySet not empty?"]
    RETURN_KEYS["Return currency code array"]
    RETURN_NULL["Return null"]
    START --> CALL_GET_URL
    CALL_GET_URL --> BUILD_URL
    BUILD_URL --> CALL_GET_JSON
    CALL_GET_JSON --> DECISION_JSON
    DECISION_JSON -->|Yes| GET_CODE
    DECISION_JSON -->|No| RETURN_NULL
    GET_CODE --> DECISION_KEYS
    DECISION_KEYS -->|Yes| RETURN_KEYS
    DECISION_KEYS -->|No| RETURN_NULL
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| - | (none) | - | This method takes no input parameters. It always derives the target currency list from the configured upstream API base URL and the fixed USD latest-rate endpoint. |

External state read by the method:
- `getURL()` from the same class, which supplies the external API base address.
- Upstream JSON payload field `conversion_rates`, which contains the supported currency codes.

## 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 | - | Resolves the base endpoint used to request the latest USD currency-rate dataset |
| R | `getJsonObject` | CurrencyRateAPI | - | Sends the HTTP request and parses the upstream JSON response body |
| R | `has` | JsonObject | - | Checks whether the response contains the `conversion_rates` payload node |
| R | `getAsJsonObject` | JsonObject | - | Reads the `conversion_rates` object from the JSON response |
| R | `keySet` | JsonObject | - | Reads the set of currency code keys from the response object |
| R | `toArray` | Set | - | Converts the currency code key set to a `String[]` for downstream consumption |

## 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] -`, `getURL [R] -` |

## 6. Per-Branch Detail Blocks

**Block 1** — Sequential setup (L61-L62)

> Builds the request URL and invokes the upstream JSON fetch.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `getURL()` // resolve the API base URL |
| 2 | SET | `JsonObject jsonObject = getJsonObject(new java.net.URI(getURL() + "/latest/" + "USD").toURL());` // call upstream latest-rates endpoint |

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

> Validates that the response contains the supported currency code map.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `jsonObject != null` // ensure the response was received |
| 2 | EXEC | `jsonObject.has("conversion_rates")` // confirm the currency map exists |

**Block 2.1** — Nested `IF` `(code != null and !code.keySet().isEmpty())` (L65)

> Confirms that the currency map is present and contains at least one code before returning it.

| # | Type | Code |
|---|------|------|
| 1 | SET | `JsonObject code = jsonObject.getAsJsonObject("conversion_rates");` // extract the currency-rate map |
| 2 | EXEC | `code != null` // verify extracted object exists |
| 3 | EXEC | `code.keySet().isEmpty()` // check whether any currency codes were returned |
| 4 | RETURN | `return code.keySet().toArray(new String[0]);` // return supported currency codes |

**Block 2.2** — `ELSE` of Block 2.1 (L65-L69)

> Handles the case where the upstream payload exists but does not contain usable currency code entries.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return null;` // no currency code list could be derived |

**Block 3** — `ELSE` of Block 2 (L63-L69)

> Handles missing or incomplete upstream responses.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return null;` // upstream payload is absent or missing conversion_rates |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `CurrencyRateAPI` | Class | External currency-rate API adapter used to call the upstream exchange-rate service and translate its response for application use. |
| `getCurrencyCode` | Method | Reads the set of supported currency codes from the latest USD rate response. |
| `getURL` | Method | Returns the configured base URL for the external currency-rate provider. |
| `getJsonObject` | Method | Executes an HTTP request and parses the response into a JSON object. |
| `conversion_rates` | JSON field | Map of supported currency codes to their exchange-rate values in the upstream response. |
| `USD` | Currency code | United States dollar — used here as the base currency for the latest-rate lookup. |
| `JsonObject` | Technical term | JSON object representation used to navigate the upstream response payload. |
| `String[]` | Technical type | Array of currency code strings returned to the caller. |
| `UI` | Class | User interface layer that consumes this API helper to populate or validate currency selections. |
| `latest` | Endpoint segment | Upstream API route that returns the most recent exchange-rate data. |
| `toURL` | Technical method | Converts a URI into a URL so it can be used for the HTTP request. |