# (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()

`CurrencyRateAPI.getJsonObject()` is a shared HTTP response reader for the currency exchange integration. It accepts a fully formed `URL`, opens a network connection, performs a `GET` request, and converts the remote service payload into a Gson `JsonObject` when the response is successful. In business terms, it is the low-level retrieval step that enables the application to consume live foreign exchange data from the external ExchangeRate API.

This method implements a simple routing-and-delegation pattern for remote calls: it routes the request to the supplied endpoint, validates the HTTP status, and delegates response interpretation to Gson JSON parsing. It does not branch by business service type itself, but it supports both downstream use cases in this class: fetching the list of supported currencies and calculating a conversion result. If the endpoint returns anything other than HTTP 200, the method logs the failure and returns `null`, allowing the caller to decide how to handle the missing exchange data.

The method also acts as a resilience boundary. It centralizes exception handling for network and parsing failures so that higher-level conversion methods do not need to repeat connection management logic. As a result, this method is a reusable integration utility rather than a screen-specific or database-specific operation.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["getJsonObject(URL url)"]
    OPEN["Open HTTP connection and cast to HttpURLConnection"]
    SET_METHOD["Set request method to GET"]
    GET_CODE["Read response code"]
    COND_OK{"responseCode == HTTP_OK"}
    PARSE["Parse response content with JsonParser.parseReader"]
    TO_OBJECT["Convert JsonElement to JsonObject"]
    LOG_ERR["Log GET failure with response code"]
    CATCH["Catch Exception and log API request error"]
    RETURN_OK["Return JsonObject"]
    RETURN_NULL["Return null"]

    START --> OPEN
    OPEN --> SET_METHOD
    SET_METHOD --> GET_CODE
    GET_CODE --> COND_OK
    COND_OK -->|HTTP_OK| PARSE
    PARSE --> TO_OBJECT
    TO_OBJECT --> RETURN_OK
    COND_OK -->|Not HTTP_OK| LOG_ERR
    LOG_ERR --> RETURN_NULL
    START --> CATCH
    CATCH --> RETURN_NULL
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `url` | `URL` | The fully qualified endpoint for the external currency exchange service. It determines which remote resource is queried, such as the supported currency list endpoint or the currency pair conversion endpoint. Different URL paths lead to different JSON response shapes, which then affect how the caller interprets the returned object. |

Instance fields and external state read by this method:
- `logger` for error logging.
- The runtime network state of the remote API endpoint referenced by `url`.

## 4. CRUD Operations / Called Services

This method does not perform database CRUD operations and does not call any internal service component or CBS method. Its only external interaction is an HTTP GET to a third-party currency exchange API, followed by JSON parsing of the response body.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `HttpURLConnection#getResponseCode` / `JsonParser.parseReader` | N/A | External ExchangeRate API response payload | Reads the remote API response and parses it into a JSON object for downstream currency lookup or conversion processing. |

## 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` | `HttpURLConnection + JsonParser [R] External ExchangeRate API response payload` |
| 2 | Controller:CurrencyRateAPI | `CurrencyRateAPI.convert` -> `CurrencyRateAPI.getJsonObject` | `HttpURLConnection + JsonParser [R] External ExchangeRate API response payload` |

The method is called only from within `CurrencyRateAPI`, which means it serves as an internal integration helper rather than a shared cross-module dependency. Both entry points are controller-like utility methods in the same class: one retrieves supported currency codes from the `conversion_rates` object, and the other retrieves a pair conversion result from the `conversion_result` field. Neither caller reaches database CRUD logic through this method.

## 6. Per-Branch Detail Blocks

**Block 1** — TRY (main HTTP request flow) (L42-L53)

> Opens the remote connection, sends a GET request, and interprets the result when the API call succeeds.

| # | 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)` |

**Block 1.1** — IF `responseCode == HTTP_OK` (L46)

> Handles the successful exchange-rate response body.

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

**Block 1.2** — ELSE `responseCode != HTTP_OK` (L48-L50)

> Logs that the external API did not return a success status.

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

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

> Handles any transport, content, or parsing failure from the remote API call.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|-------------------|
| `CurrencyRateAPI` | Class | Utility class that communicates with the external currency exchange service and exposes currency lookup and conversion operations. |
| `getJsonObject` | Method | Shared helper that performs the HTTP GET request and converts the remote JSON payload into a `JsonObject`. |
| `url` | Field / Parameter | Target endpoint for the external API call. |
| `HttpURLConnection` | Technical term | Java networking class used to perform HTTP requests. |
| `HTTP_OK` | Constant | HTTP 200 success status indicating the remote service returned a valid response. |
| `JsonObject` | Technical term | Gson JSON object representation used by downstream currency processing methods. |
| `JsonElement` | Technical term | Gson intermediate JSON representation before conversion to `JsonObject`. |
| `JsonParser` | Technical term | Gson parser used to transform the response body into JSON structures. |
| `conversion_rates` | JSON field | Map of supported currency codes returned by the external service for a base currency. |
| `conversion_result` | JSON field | Numeric conversion output returned by the external service for a currency pair calculation. |
| ExchangeRate API | Business term | Third-party foreign exchange service used to retrieve live currency codes and conversion values. |
| API key | Acronym / credential term | Authentication value used to authorize requests to the external exchange service. |
| GET | HTTP method | Read-only request used to fetch exchange-rate data without modifying remote state. |
| `logger` | Technical term | Logging facility used to record API failures and exceptions. |