---
# (DD07) Business Logic — CurrencyRateAPI.getJsonObject() [17 LOC]

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

## 1. Role

### CurrencyRateAPI.getJsonObject()

This method is the low-level HTTP retrieval and JSON parsing entry point used by `CurrencyRateAPI` to turn an external exchange-rate API endpoint into a structured `JsonObject`. Business-wise, it acts as the shared transport adapter for currency-related lookups: it sends a GET request to the configured endpoint, confirms the remote service replied successfully, and then converts the response payload into Gson JSON for the higher-level currency functions to consume.

The method supports a single execution path with two major outcomes: a successful HTTP 200 response is parsed and returned as a `JsonObject`, while any non-OK response or runtime exception is logged and results in `null`. It implements a simple routing/delegation pattern by centralizing API access so that `getCurrencyCode()` and `convert()` do not duplicate connection and parsing logic. In the larger system, this method is a reusable infrastructure helper inside the API client class rather than a business rule engine; it isolates network access, response validation, and JSON deserialization behind one method boundary.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
START(["getJsonObject(url)"])
OPEN["Open HTTP connection"]
SET_METHOD["Set request method to GET"]
GET_CODE["Read HTTP response code"]
COND_OK{"responseCode == HTTP_OK"}
PARSE["Parse response body to JsonObject"]
RETURN_JSON["Return JsonObject"]
LOG_FAIL["Log GET failure with response code"]
CATCH["Catch Exception and log API request error"]
RETURN_NULL["Return null"]
END_NODE(["End"])
START --> OPEN
OPEN --> SET_METHOD
SET_METHOD --> GET_CODE
GET_CODE --> COND_OK
COND_OK -->|Yes| PARSE
PARSE --> RETURN_JSON
COND_OK -->|No| LOG_FAIL
LOG_FAIL --> RETURN_NULL
CATCH --> RETURN_NULL
RETURN_JSON --> END_NODE
RETURN_NULL --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `url` | `URL` | Target endpoint for the external currency-rate API call. It determines which remote service resource is queried, including the currency endpoint and any path parameters embedded by the caller. A valid URL results in an HTTP GET request; an unreachable or malformed endpoint causes the method to log an error and return `null`. |

Instance fields and external state read by the method:
- `logger` — records HTTP and exception failures.
- External network response from the remote exchange-rate API.

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `getJsonObject(URL)` | N/A | Remote ExchangeRate API response payload | Sends an HTTP GET request and reads the remote JSON response body for downstream currency processing. |

The method does not access a local database, entity repository, or internal CBS/SC component. Its only dependency is the external API response returned through `HttpURLConnection`.

## 5. Dependency Trace

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

| # | Caller (Screen/Batch) | Call Chain (Full Path to Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|----------------------------------|-------------------------------|
| 1 | Controller:CurrencyRateAPI | `CurrencyRateAPI.getCurrencyCode` -> `CurrencyRateAPI.getJsonObject` | `getJsonObject [R] Remote ExchangeRate API response payload` |
| 2 | Controller:CurrencyRateAPI | `CurrencyRateAPI.convert` -> `CurrencyRateAPI.getJsonObject` | `getJsonObject [R] Remote ExchangeRate API response payload` |

The method is called only from within the same `CurrencyRateAPI` class. `getCurrencyCode()` uses it to obtain the `/latest/USD` response and extract supported currency codes, while `convert()` uses it to obtain the `/pair/...` response and read the conversion result. No screen, batch, or CBS caller is present in the analyzed source set.

## 6. Per-Branch Detail Blocks

**Block 1** — `TRY` `(request setup and response handling)` (L42-L54)

> This block performs the full lifecycle of the outbound HTTP call and response conversion.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `HttpURLConnection request = (HttpURLConnection) url.openConnection();` |
| 2 | EXEC | `request.setRequestMethod("GET");` |
| 3 | SET | `int responseCode = request.getResponseCode();` |
| 4 | IF | `if (responseCode == HttpURLConnection.HTTP_OK)` [HTTP_OK="200"] |

**Block 1.1** — `IF` `(responseCode == HTTP_OK)` [HTTP_OK="200"] (L46)

> Successful remote response is parsed into structured JSON for downstream business logic.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `JsonElement root = JsonParser.parseReader(new InputStreamReader((InputStream) request.getContent()));` |
| 2 | EXEC | `root.getAsJsonObject();` |
| 3 | RETURN | `return root.getAsJsonObject();` |

**Block 1.2** — `ELSE` `(responseCode != HTTP_OK)` (L49)

> Non-success response is treated as a recoverable integration failure and logged for support diagnostics.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `logger.error("GET request failed with response code: {}", responseCode);` |

**Block 2** — `CATCH` `(Exception e)` (L51-L53)

> Any transport, parsing, or runtime failure is captured and logged, then the method returns no data.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `logger.error("An error occurred during the API request", e);` |
| 2 | RETURN | `return null;` |

**Block 3** — `RETURN` `(fall-through after failed request)` (L55)

> The method exits with a null payload when the exchange-rate response cannot be trusted or produced.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `url` | Field/Parameter | Target remote endpoint used to request exchange-rate data. |
| `logger` | Technical term | Application logger used to record HTTP and exception failures. |
| `HTTP_OK` | Constant | HTTP status code 200, meaning the remote request succeeded. |
| `JsonObject` | Technical term | Structured JSON object returned by Gson after parsing the API response. |
| `JsonElement` | Technical term | Gson base JSON node type returned by the parser before object conversion. |
| `JsonParser` | Technical term | Gson parser used to convert response text into JSON structures. |
| `HttpURLConnection` | Technical term | Java networking API used to send the outbound HTTP GET request. |
| `InputStreamReader` | Technical term | Bridges the response byte stream into character data for JSON parsing. |
| `ExchangeRate API` | Business term | External currency exchange-rate service providing latest rates and conversion results. |
| `conversion_rates` | JSON field | Map of supported currency codes to exchange-rate values in the latest-rates response. |
| `conversion_result` | JSON field | Converted amount returned by the pair-conversion endpoint. |
| `USD` | Currency code | United States Dollar, used as the base currency in the caller method `getCurrencyCode()`. |
| `pair` | API path segment | Exchange-rate API route for converting one currency into another. |
| `latest` | API path segment | Exchange-rate API route for retrieving the latest currency-rate table. |
| `API_KEY` | Configuration key | Property name used to read the external API authentication token from `config.properties`. |
| `config.properties` | Configuration file | Application properties file containing integration settings, including the exchange-rate API key. |
| `GET` | HTTP method | Read-only HTTP verb used to retrieve data from the remote API. |