# (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 performs the low-level HTTP retrieval and JSON conversion for a currency-rate API endpoint. Business-wise, it acts as the shared transport adapter that turns a remote REST response into an in-memory `JsonObject` so the rest of `CurrencyRateAPI` can consume exchange-rate data without dealing with HTTP plumbing. The method is responsible for a single external service interaction pattern: open a URL connection, issue a GET request, verify the response status, and deserialize the payload when the call succeeds.

The method supports two business outcomes only. If the remote service returns HTTP 200 (`HTTP_OK`), it converts the response body into a `JsonObject` and returns it to the caller. If the response is not successful, it records an error with the response code and returns `null`. Any exception during connection setup, request execution, or parsing is also trapped, logged, and converted into a `null` result. In the larger system, this method functions as a reusable utility for currency exchange lookups, allowing higher-level methods such as `convert` and `getCurrencyCode` to focus on business transformations instead of API communication.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["getJsonObject(url)"])
    OPEN_CONN["Open HTTP connection from URL"]
    SET_GET["Set request method to GET"]
    GET_CODE["Read response code"]
    OK_DECISION{"responseCode == HTTP_OK
200"}
    PARSE_JSON["Parse response stream into JsonObject"]
    RETURN_JSON["Return JsonObject"]
    LOG_FAIL["Log GET request failure with response code"]
    CATCH_ERR["Catch exception and log API request error"]
    RETURN_NULL["Return null"]

    START --> OPEN_CONN --> SET_GET --> GET_CODE --> OK_DECISION
    OK_DECISION -->|Yes| PARSE_JSON --> RETURN_JSON --> RETURN_NULL
    OK_DECISION -->|No| LOG_FAIL --> RETURN_NULL
    GET_CODE --> CATCH_ERR --> RETURN_NULL
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `url` | `URL` | The fully qualified endpoint location for the external currency-rate service. It represents the remote business API address to call, and its value determines which currency data resource is requested. If the URL is valid and the service responds with HTTP 200, the response payload is returned as JSON; otherwise the method logs the failure and returns `null`. |

External state read by the method:
- `logger` — used for error logging when the HTTP call fails or an exception occurs.

## 4. CRUD Operations / Called Services

This method does not call internal business services, DAO methods, or database CRUD components. Its only operational dependencies are standard JDK networking and JSON parsing APIs, which are infrastructure-level reads rather than business CRUD operations.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `url.openConnection()` | - | Remote HTTP endpoint | Opens the outbound connection to the external currency API resource. |
| U | `request.setRequestMethod("GET")` | - | HTTP request metadata | Sets the transport method to GET for a read-only retrieval request. |
| R | `request.getResponseCode()` | - | Remote HTTP endpoint | Reads the server response status to determine whether the payload can be consumed. |
| R | `request.getContent()` | - | Remote HTTP response body | Reads the response body stream for JSON parsing. |
| R | `JsonParser.parseReader(...)` | - | JSON payload | Deserializes the remote response into a JSON object model. |

## 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.convert` -> `CurrencyRateAPI.getJsonObject` | - |
| 2 | Controller:CurrencyRateAPI | `CurrencyRateAPI.getCurrencyCode` -> `CurrencyRateAPI.getJsonObject` | - |

### Caller search results

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

## 6. Per-Branch Detail Blocks

**Block 1** — TRY (main execution path) (L42)

> Opens the remote endpoint, issues a GET request, and determines whether the payload can be safely parsed.

| # | 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)` [HTTP_OK="200"] (L46)

> Successful remote lookup path. The response body is treated as JSON and returned to the caller.

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

**Block 1.2** — ELSE (response code is not HTTP 200) (L48)

> Failure path for non-success HTTP responses. The method records the response code for operational monitoring and returns no data.

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

**Block 2** — CATCH `(Exception e)` (L50)

> Exception handling path for connection, transport, or parsing failures.

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

**Block 3** — FALLBACK RETURN (L53)

> Default completion path when neither the success branch nor the exception path returns a value.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `url` | Field/Parameter | Remote endpoint location for the external currency-rate service request. |
| HTTP | Acronym | Hypertext Transfer Protocol — standard protocol used for web requests. |
| GET | Acronym | HTTP read operation used to retrieve a resource without modifying it. |
| JSON | Acronym | JavaScript Object Notation — lightweight structured data format returned by the remote API. |
| `JsonObject` | Technical term | In-memory JSON container representing the successful API payload. |
| `JsonParser` | Technical term | JSON library component that converts text input into JSON model objects. |
| `InputStreamReader` | Technical term | Adapter that converts a byte stream from the HTTP response into character data for parsing. |
| `HttpURLConnection` | Technical term | JDK networking class used to execute HTTP requests. |
| `HTTP_OK` | Constant | HTTP status code `200`, meaning the remote service returned a successful response. |
| `logger` | Technical term | Logging facility used to record failed requests and exceptions for diagnostics. |
| `CurrencyRateAPI` | Class | API-facing utility that retrieves and transforms exchange-rate data from an external service. |
| `convert` | Method | Higher-level currency conversion routine that depends on this JSON retrieval helper. |
| `getCurrencyCode` | Method | Higher-level currency code lookup routine that depends on this JSON retrieval helper. |