# (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(URL url)` is the low-level HTTP retrieval routine that turns an external API endpoint into an in-memory JSON object for the currency-rate workflow. Its business responsibility is to execute a synchronous GET request, validate the transport-level response, and expose the payload as a structured `JsonObject` so upstream conversion logic can read fields such as conversion results without dealing with HTTP mechanics.

The method implements a simple routing-and-translation pattern: it routes the supplied endpoint through `HttpURLConnection`, applies the fixed request method `GET`, and then translates a successful response body into a JSON model. If the remote service does not return `HTTP_OK`, the method treats the operation as a failed retrieval and records the failure through logging rather than throwing a domain-specific exception. This makes the method a shared integration utility inside `CurrencyRateAPI`, separating API transport handling from currency conversion logic.

In the broader system, the method acts as a reusable outbound-call helper for two public API workflows in the same class: base-currency lookup and currency pair conversion. It is not a CRUD method against an internal database; instead, it is an external read operation against a remote service endpoint. The method also provides a defensive null-return fallback so callers can decide whether to continue processing or stop when the remote response is missing or invalid.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["getJsonObject(url)"])
    A["Create HttpURLConnection from URL"]
    B["Set request method to GET"]
    C["Read HTTP response code"]
    D{"responseCode == HttpURLConnection.HTTP_OK?"}
    E["Parse response body with JsonParser.parseReader"]
    F["Convert parsed JSON to JsonObject"]
    G["Return JsonObject"]
    H["Log error for non-OK response"]
    I["Catch Exception"]
    J["Log error for request failure"]
    K["Return null"]
    START --> A
    A --> B
    B --> C
    C --> D
    D -->|Yes| E
    E --> F
    F --> G
    D -->|No| H
    H --> K
    I --> J
    J --> K
```

**Constant resolution:** `HttpURLConnection.HTTP_OK = 200`, which is the standard HTTP success status used to confirm that the remote currency service returned a valid response body.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `url` | `URL` | Target endpoint for the external currency-rate service. It carries the fully constructed request address for the specific business query, such as latest-rate retrieval or currency-pair conversion. The method always uses it as a read-only outbound request destination; if the URL is invalid, unreachable, or produces a non-OK response, processing falls back to error logging and `null`. |

Instance fields / external state read by the method:
- `logger` — used to record transport failures and exception details.
- `HttpURLConnection.HTTP_OK` — standard Java constant controlling the success branch.

## 4. CRUD Operations / Called Services

This method performs no internal database CRUD operations. Its only data-access action is an external read against a remote HTTP API, followed by JSON parsing.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `url.openConnection()` / `request.getResponseCode()` / `JsonParser.parseReader(...)` | N/A | External currency-rate API response | Reads the remote API endpoint, validates the HTTP response, and parses the returned payload into a JSON object for downstream business use. |

Called methods and their functional classification inside this method:
- `url.openConnection()` — initializes the outbound connection object.
- `request.setRequestMethod("GET")` — configures the connection as a read-only retrieval.
- `request.getResponseCode()` — reads the HTTP status returned by the remote service.
- `JsonParser.parseReader(...)` — converts the successful response stream into structured JSON.
- `request.getContent()` — accesses the response body stream.
- `root.getAsJsonObject()` — extracts the JSON object from the parsed payload.
- `logger.error(...)` — records failure conditions for operational traceability.

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

`getJsonObject(URL url)` is a private outbound helper that is only reached from two public methods in the same class. The entry paths both originate in `CurrencyRateAPI` itself, so the dependency is internal and tightly scoped rather than shared across screens or batches. Both callers rely on this method to normalize remote JSON responses before they continue with currency-code extraction or pair-conversion logic.

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

## 6. Per-Branch Detail Blocks

**Block 1** — TRY `(initial HTTP request setup)` (L42-L44)

> Opens the outbound connection and prepares it as a read-only request to the remote currency-rate endpoint.

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

**Block 2** — TRY `(response validation)` (L46-L47)

> Reads the service status code and routes processing based on whether the remote endpoint returned a successful HTTP response.

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

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

> Success path: parse the returned payload and expose it as a JSON object for downstream business logic.

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

**Block 2.2** — ELSE `(responseCode != HttpURLConnection.HTTP_OK)` [HTTP_OK="200"] (L50-L51)

> Failure path for non-success HTTP status codes; logs the transport failure and exits without a JSON payload.

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

**Block 3** — CATCH `(Exception e)` (L52-L54)

> Handles any runtime or checked exception raised during request setup, response reading, or JSON parsing.

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

**Block 4** — RETURN `(fallback path)` (L56)

> Common fallback return when the HTTP call fails or an exception occurs.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|-------------------|
| `url` | Field/Parameter | Fully qualified endpoint for the external currency-rate request. |
| `HttpURLConnection` | Technical term | Standard Java HTTP client connection used to execute outbound REST-style requests. |
| `GET` | Acronym/HTTP method | Read-only retrieval request used to fetch currency-rate data. |
| `HTTP_OK` | Acronym/Constant | HTTP success status code `200`, indicating a valid response from the remote API. |
| `JsonParser` | Technical term | Gson parser that converts response text into structured JSON. |
| `JsonElement` | Technical term | Generic JSON node produced by parsing the response body. |
| `JsonObject` | Technical term | JSON object representation returned to the caller for field-based access. |
| `logger` | Technical term | Application logging facility used to record failures and exceptions. |
| `CurrencyRateAPI` | Component | API integration helper that retrieves and converts currency exchange data. |
| `conversion_result` | JSON field | Numeric result returned by the remote currency conversion endpoint. |
| `getCurrencyCode` | Method | Public helper that retrieves latest currency data for base-code extraction. |
| `convert` | Method | Public helper that requests a currency pair conversion result. |
| `External API` | Business term | Third-party exchange-rate service accessed over HTTP rather than internal persistence. |
| `Response code` | Technical term | HTTP status returned by the remote service; determines success or failure routing. |
| `null` | Technical term | Absence of a usable JSON object, used here to indicate request failure or parsing failure. |