---
# (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 shared HTTP response reader for the currency-rate API client. It performs a GET request against the provided endpoint URL, verifies that the remote service returned an OK status, and converts the response payload into a `JsonObject` for downstream business use. In practice, it acts as the common JSON acquisition step behind higher-level currency operations such as retrieving available currency codes and performing currency conversion lookups.

The method follows a routing-and-delegation pattern: it centralizes the transport, response-code check, and JSON parsing so that the caller methods do not need to duplicate HTTP handling logic. It is not a business rule engine by itself; rather, it is an integration utility that protects the rest of the system from raw HTTP and stream-handling complexity. When the remote API responds successfully, the parsed JSON object is returned to the caller; when the response is not successful or an exception occurs, the method records the failure and returns `null`.

## 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 response code"]
    OK_DECISION{"responseCode == HTTP_OK"}
    PARSE["Parse response stream to JsonElement"]
    TO_JSON["Return root.getAsJsonObject()"]
    LOG_FAIL["Log GET request failure with response code"]
    LOG_EX["Log exception during API request"]
    RETURN_NULL["Return null"]
    CATCH["Catch Exception"]

    START --> OPEN
    OPEN --> SET_METHOD
    SET_METHOD --> GET_CODE
    GET_CODE --> OK_DECISION
    OK_DECISION -->|Yes| PARSE
    PARSE --> TO_JSON
    TO_JSON --> RETURN_NULL
    OK_DECISION -->|No| LOG_FAIL
    LOG_FAIL --> RETURN_NULL
    GET_CODE --> CATCH
    CATCH --> LOG_EX
    LOG_EX --> RETURN_NULL
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `url` | `URL` | Remote currency API endpoint to be queried. It represents the exact business request target, such as a latest-rate lookup or a currency-pair conversion lookup, and determines what JSON document will be returned. |

External state read by the method:
- No instance fields are read directly inside `getJsonObject(URL url)`.
- The method relies on the runtime HTTP response from the passed endpoint and on the shared logger for failure reporting.

## 4. CRUD Operations / Called Services

This method does not perform database CRUD operations. It is an external read-only integration call that retrieves JSON from an HTTP endpoint and returns the parsed payload.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `url.openConnection()` / `request.getResponseCode()` / `request.getContent()` | N/A | External currency API endpoint | Reads the remote API response for the supplied currency service URL. |
| R | `JsonParser.parseReader(...)` | N/A | JSON response payload | Converts the HTTP response stream into an in-memory JSON structure. |

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

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 | Controller:CurrencyRateAPI | `CurrencyRateAPI.getCurrencyCode` -> `CurrencyRateAPI.getJsonObject` | `JsonParser.parseReader(...) [R] External currency API endpoint` |
| 2 | Controller:CurrencyRateAPI | `CurrencyRateAPI.convert` -> `CurrencyRateAPI.getJsonObject` | `JsonParser.parseReader(...) [R] External currency API endpoint` |
| 3 | Screen:UI | `UI.CurrencyCode.doInBackground` -> `CurrencyRateAPI.getCurrencyCode` -> `CurrencyRateAPI.getJsonObject` | `JsonParser.parseReader(...) [R] External currency API endpoint` |

## 6. Per-Branch Detail Blocks

**Block 1** — `TRY` (L42-L58)

> Main integration path for obtaining and parsing a JSON response from the external currency service.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `HttpURLConnection request = (HttpURLConnection) url.openConnection();` // Open a connection to the requested API endpoint |
| 2 | EXEC | `request.setRequestMethod("GET");` // Force a read-only HTTP GET request |
| 3 | SET | `int responseCode = request.getResponseCode();` // Capture the remote service status code |
| 4 | IF | `if (responseCode == HttpURLConnection.HTTP_OK)` // Proceed only when the API returns success |

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

> Success branch: parse the API response body into a JSON object and return it to the caller.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `JsonElement root = JsonParser.parseReader(new InputStreamReader((InputStream) request.getContent()));` // Convert the response stream into a JSON element |
| 2 | RETURN | `return root.getAsJsonObject();` // Return the parsed JSON payload to the higher-level caller |

**Block 1.2** — `ELSE` `(responseCode != HttpURLConnection.HTTP_OK)` (L48)

> Failure branch: record the HTTP error status for diagnostics and stop processing.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `logger.error("GET request failed with response code: {}", responseCode);` // Log the non-success response code |
| 2 | RETURN | `return null;` // Signal that no JSON object could be produced |

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

> Exception branch: handle transport, parsing, or runtime failures during the request lifecycle.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `logger.error("An error occurred during the API request", e);` // Record the exception with stack trace |
| 2 | RETURN | `return null;` // Signal that no JSON object could be produced |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|-------------------|
| `url` | Field/Parameter | Fully qualified endpoint address for the external currency-rate service request. |
| `GET` | Technical term | HTTP read operation used to fetch a resource without changing remote state. |
| `HTTP_OK` | Technical constant | Standard HTTP success status code 200, indicating that the request completed successfully. |
| `JsonObject` | Technical type | In-memory JSON object representation returned to callers after parsing the API response. |
| `JsonElement` | Technical type | Generic JSON node type used as an intermediate parsing result before conversion to `JsonObject`. |
| `JsonParser` | Technical component | Gson parser used to transform response text or stream data into JSON structures. |
| `InputStreamReader` | Technical component | Converts the HTTP byte stream into characters for JSON parsing. |
| `request` | Local variable | The active HTTP connection used to communicate with the remote currency service. |
| `responseCode` | Local variable | HTTP status returned by the remote service, used to decide whether parsing should continue. |
| `logger` | Technical component | Logging facility used to record API failures and exceptions for support diagnostics. |
| currency API | Business term | External service that provides exchange-rate and conversion data. |
| conversion result | Business term | Numeric outcome returned by the API when converting one currency into another. |
| latest rates | Business term | Current exchange-rate snapshot for a base currency. |
| external service | Business term | Third-party HTTP endpoint outside the local application boundary. |
| CurrencyRateAPI | Class | Application API client that builds currency requests and interprets returned JSON data. |
| `getCurrencyCode` | Method | Higher-level caller that retrieves supported currency codes from the latest-rates payload. |
| `convert` | Method | Higher-level caller that requests a currency-pair conversion result from the remote API. |
| `UI.CurrencyCode.doInBackground` | Screen workflow | Background UI job that invokes currency-code retrieval for the user interface. |
| `conversion_rates` | JSON field | Map of supported currency codes returned by the latest-rates endpoint. |
| `conversion_result` | JSON field | Computed amount returned by the pair-conversion endpoint. |