# (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 normalization entry point for the currency rate API integration. Its business responsibility is to call an external exchange-rate endpoint, request the response using the HTTP GET method, and convert a successful response body into a `JsonObject` that the rest of the application can consume. In effect, it acts as a shared transport adapter between URL-based API endpoints and the application’s currency conversion workflows.

The method implements a simple routing-and-delegation pattern: it opens the network connection, executes the request, checks the transport outcome, and either returns a parsed JSON payload or logs an error and returns `null`. It has two explicit failure branches: one for a non-200 HTTP response and one for any exception thrown while opening the connection, reading the response, or parsing the payload. The method does not transform business data itself; instead, it standardizes access to external API results so that higher-level methods such as currency code lookup and currency conversion can reuse the same HTTP handling logic.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["getJsonObject(url)"])
    OPEN["Open HttpURLConnection from URL"]
    SET_METHOD["Set request method to GET"]
    GET_CODE["Read response code"]
    DECISION{"responseCode == HTTP_OK"}
    PARSE["Parse response body via JsonParser.parseReader"]
    RETURN_JSON["Return JsonObject"]
    LOG_FAIL["Log failed GET response code"]
    LOG_ERROR["Log exception during API request"]
    RETURN_NULL["Return null"]

    START --> OPEN
    OPEN --> SET_METHOD
    SET_METHOD --> GET_CODE
    GET_CODE --> DECISION
    DECISION -->|Yes| PARSE
    PARSE --> RETURN_JSON
    DECISION -->|No| LOG_FAIL
    LOG_FAIL --> RETURN_NULL
    START --> LOG_ERROR
    LOG_ERROR --> RETURN_NULL
```

**Constant Resolution:**
This method does not reference any application constants or constant-driven business codes. The HTTP status check uses the JDK constant `HttpURLConnection.HTTP_OK`, which is a framework-level transport status and not a project-specific business constant.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `url` | `URL` | Fully qualified endpoint address for the external currency-rate service. It identifies which API resource will be called, including the path and query structure chosen by the caller. Different URL values drive different currency business functions, such as exchange-rate list retrieval or pair conversion. |

External state read by this method:
- `logger` — used to record failed HTTP responses and caught exceptions.

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `HttpURLConnection.openConnection` / HTTP transport | N/A | External currency-rate API | Opens a network connection to read exchange-rate data from the remote service. |
| R | `HttpURLConnection.getResponseCode` | N/A | External currency-rate API | Reads the HTTP status to determine whether the remote response is usable. |
| R | `JsonParser.parseReader` | N/A | JSON response payload | Deserializes the successful response body into a JSON object for downstream use. |

This method performs no local database CRUD and no SC/CBS service calls. Its operations are read-only and transport-oriented.

## 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` | `JsonParser.parseReader [R] External currency-rate API payload` |
| 2 | Controller:CurrencyRateAPI | `CurrencyRateAPI.convert` -> `CurrencyRateAPI.getJsonObject` | `JsonParser.parseReader [R] External currency-rate API payload` |

The method is called only by sibling public methods inside `CurrencyRateAPI`. `getCurrencyCode()` uses it to retrieve the latest exchange-rate catalog, while `convert()` uses it to retrieve a pair conversion result. Both callers depend on the same JSON parsing and HTTP error handling behavior, so this method serves as the shared dependency for all outbound currency API reads in the class.

## 6. Per-Branch Detail Blocks

**Block 1** — TRY (method entry and HTTP request setup) (L42-L44)

> Opens the remote API connection and prepares a GET request.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `HttpURLConnection request = (HttpURLConnection) url.openConnection();` |
| 2 | EXEC | `request.setRequestMethod("GET");` |

**Block 2** — TRY (response handling) (L46-L51)

> Checks whether the remote service returned a successful HTTP response and parses the body only when the call succeeded.

| # | Type | Code |
|---|------|------|
| 1 | SET | `int responseCode = request.getResponseCode();` |
| 2 | IF | `responseCode == HttpURLConnection.HTTP_OK` [HTTP_OK = 200] |

**Block 2.1** — IF success branch (L47-L48)

> Converts the HTTP response payload into a JSON object that can be consumed by higher-level currency operations.

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

**Block 2.2** — ELSE failure branch (L49-L50)

> Logs the non-success response code for operational visibility and returns no data.

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

**Block 3** — CATCH (exception handling) (L52-L54)

> Captures transport, parsing, or runtime errors from the external API call and writes an error log.

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

**Block 4** — POST-TRY fallback return (L56)

> Provides a final null return path when no successful response was produced.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `url` | Field/Parameter | Fully qualified endpoint address for the external currency-rate service request. |
| HTTP | Acronym | Hypertext Transfer Protocol — standard protocol used for client-server web communication. |
| GET | Acronym | HTTP read operation used to retrieve data without modifying the remote system. |
| `HTTP_OK` | Technical constant | HTTP status 200 indicating that the remote API returned a successful response. |
| `JsonObject` | Technical type | JSON container representing the structured response returned by the currency API. |
| `JsonElement` | Technical type | Intermediate JSON representation used before converting to a JSON object. |
| `JsonParser` | Technical component | JSON parsing utility that converts a character stream into structured JSON. |
| `InputStreamReader` | Technical component | Bridge that converts the byte stream from the HTTP response into characters for JSON parsing. |
| `HttpURLConnection` | Technical component | JDK HTTP client connection class used to call the remote exchange-rate endpoint. |
| `logger` | Technical field | Logging facility used to record failures and exceptions during API communication. |
| currency rate API | Business term | External service that supplies exchange-rate data for currency lookup and conversion workflows. |
| conversion result | Business term | Numeric outcome returned by the external API when converting one currency amount into another. |
| conversion rates | Business term | Set of available currency exchange rates returned by the external API for the requested base currency. |