---

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

`getJsonObject(URL url)` is a low-level HTTP response acquisition method that executes a GET request against an externally supplied endpoint, checks whether the remote service returned a successful HTTP status, and converts the response body into a Gson `JsonObject`. In business terms, it acts as the common network gateway for currency-rate API calls, isolating the details of connection setup, response-code validation, and JSON parsing from the higher-level currency lookup and conversion methods.

The method supports a single service category: REST-style currency exchange requests. It follows a simple routing/delegation pattern in which the caller constructs the target URL and this method performs the transport and serialization work. If the HTTP call succeeds (`HTTP_OK`), the payload is parsed and returned for downstream business logic; otherwise the method records an error and returns `null` so the caller can decide whether to continue or fail. This makes the method a shared utility for API consumption rather than a business-rule engine.

Because the method contains a success path, a non-OK response path, and an exception-handling path, it provides a centralized fault-tolerance boundary for all currency API interactions in the class. It does not transform domain values itself; instead, it standardizes the mechanics of fetching JSON so that other methods can focus on extracting exchange rates or conversion results.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["getJsonObject(url)"]
    OPEN_CONN["Open HTTP connection"]
    SET_METHOD["Set request method to GET"]
    GET_CODE["Read response code"]
    DECISION{"responseCode == HTTP_OK"}
    PARSE["Parse response stream as JSON"]
    RETURN_JSON["Return JsonObject"]
    LOG_FAIL["Log failed GET response code"]
    CATCH["Catch Exception and log API request error"]
    RETURN_NULL["Return null"]

    START --> OPEN_CONN
    OPEN_CONN --> SET_METHOD
    SET_METHOD --> GET_CODE
    GET_CODE --> DECISION
    DECISION -->|Yes| PARSE
    PARSE --> RETURN_JSON
    DECISION -->|No| LOG_FAIL
    LOG_FAIL --> RETURN_NULL
    START --> CATCH
    CATCH --> RETURN_NULL
```

**Constant Resolution:**
No project constant files were present in the available source set, and this method does not reference any application constants. The only constant comparison is against the JDK value `HttpURLConnection.HTTP_OK`, which represents the standard HTTP 200 success code.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `url` | `URL` | The fully resolved external API endpoint to call for exchange-rate data or currency-conversion data. It determines which remote service resource is queried and therefore controls the returned JSON payload. |

**External state read by the method:**
- `logger` — records failures when the HTTP response code is not successful or when an exception occurs.

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `openConnection()` / `getResponseCode()` / `JsonParser.parseReader()` | N/A | External HTTP endpoint response stream | Reads a remote REST resource and materializes the JSON response body. |

`getJsonObject` does not call any internal SC/CBS services or database access methods. Its only operational dependency is an external HTTP request followed by JSON parsing of the returned stream.

## 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 HTTP response stream` |
| 2 | Controller:CurrencyRateAPI | `CurrencyRateAPI.convert` -> `CurrencyRateAPI.getJsonObject` | `JsonParser.parseReader [R] External HTTP response stream` |

`getJsonObject` is invoked only from sibling methods in the same `CurrencyRateAPI` class. `getCurrencyCode()` uses it to retrieve the latest currency-rate list, and `convert()` uses it to retrieve a pair conversion result. The method’s terminal dependency is the remote HTTP response stream, which is read and converted into a `JsonObject` for downstream use.

## 6. Per-Branch Detail Blocks

**Block 1** — TRY `(network call and JSON parsing)` (L42-L56)

> Executes the external API request and handles both successful and unsuccessful outcomes.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `HttpURLConnection request = (HttpURLConnection) url.openConnection();` // open HTTP connection to the supplied endpoint |
| 2 | EXEC | `request.setRequestMethod("GET");` // force a read-only request |
| 3 | SET | `int responseCode = request.getResponseCode();` // capture HTTP status |
| 4 | IF | `if (responseCode == HttpURLConnection.HTTP_OK)` // `HTTP_OK = 200` |

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

> Successful response path: parse the returned JSON body and hand it to the caller.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `JsonElement root = JsonParser.parseReader(new InputStreamReader((InputStream) request.getContent()));` // read and parse the remote payload |
| 2 | RETURN | `return root.getAsJsonObject();` // return the response as a `JsonObject` |

**Block 1.2** — ELSE `(responseCode != HTTP_OK)` `[HTTP_OK="200"]` (L48)

> Failure path: log the unsuccessful HTTP status for operational diagnosis.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `logger.error("GET request failed with response code: {}", responseCode);` // record the non-OK status |

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

> Exception-handling path: capture transport, parsing, or runtime failures and log them centrally.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `logger.error("An error occurred during the API request", e);` // record the exception details |

**Block 3** — RETURN `(normal exit after try/catch)` (L54)

> If the method cannot return a parsed response, it falls back to `null` so the caller can handle the absence of data.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return null;` // indicate that the JSON response could not be obtained |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `url` | Field | Fully qualified remote endpoint address used to request exchange-rate JSON data. |
| `JsonObject` | Technical term | Gson object model representing a JSON document returned by the API. |
| `JsonElement` | Technical term | Generic Gson JSON node used as an intermediate parse result before object conversion. |
| `JsonParser` | Technical term | Gson parser that converts a character stream into a JSON tree. |
| `HttpURLConnection` | Technical term | JDK HTTP client used to send a request and read the remote response. |
| `HTTP_OK` | Constant | Standard HTTP 200 success code indicating that the remote request succeeded. |
| `GET` | HTTP method | Read-only request method used to retrieve exchange-rate data without modifying the remote system. |
| `config.properties` | Configuration file | Application property file used elsewhere in the class to obtain the API key for currency service access. |
| API | Acronym | Application Programming Interface — external service endpoint exposed for software-to-software communication. |
| REST | Acronym | Representational State Transfer — request/response style used by the exchange-rate service. |
| Currency rate | Business term | Conversion ratio between two currencies, used for lookup and monetary conversion. |
| Conversion result | Business term | Calculated amount returned by the external currency service after applying the selected exchange rate. |
| External response stream | Technical term | Raw byte stream returned by the remote HTTP service before JSON parsing. |
| logger | Technical term | Application logging facility used for operational error reporting. |
| Exception | Technical term | Runtime or checked failure condition raised during connection, I/O, or parsing operations. |
| `getCurrencyCode()` | Method | Sibling helper that retrieves available currency codes from the same API wrapper. |
| `convert()` | Method | Sibling helper that performs a currency conversion lookup using the same JSON retrieval path. |