# Com / Github / Blaxk3 / Api

## Overview

The `com.github.blaxk3.api` package appears to provide a small HTTP client wrapper around the ExchangeRate API. Its responsibilities are limited but important: load an API key from `config.properties`, build API endpoint URLs, fetch and parse JSON responses, and expose a couple of convenience methods for currency metadata and conversion.

This module exists to isolate remote API access behind a single class so the rest of the application does not need to know where the API key lives, how requests are formed, or how response JSON is parsed.

## Key Classes and Interfaces

### [CurrencyRateAPI](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:19)

`CurrencyRateAPI` is the only class in this package and acts as a lightweight service client for ExchangeRate API calls. It is state-free apart from a shared SLF4J logger, so each method can be called independently.

#### Responsibilities

- Read the API key from the application classpath
- Build the base service URL
- Execute HTTP GET requests
- Parse JSON responses into `JsonObject`
- Expose higher-level helpers for supported currency codes and conversion results

#### Important methods

- [getApiKeyService()](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:23) reads `config.properties` from the classpath and returns the `API_KEY` property.
- [getURL()](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:38) builds the base ExchangeRate API URL using the configured key.
- [getJsonObject(URL url)](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:42) performs a GET request and parses the response body as JSON.
- [getCurrencyCode()](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:61) calls the `latest/USD` endpoint and extracts the set of currency codes from `conversion_rates`.
- [convert(String foreignCurrency1, String foreignCurrency2, BigDecimal amount)](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:72) calls the pair-conversion endpoint and returns the `conversion_result` field as a string.

## How It Works

### Request flow

A typical operation follows this sequence:

1. `getURL()` asks `getApiKeyService()` for the configured API key.
2. The caller appends a resource path such as `/latest/USD` or `/pair/EUR/USD/10`.
3. `getJsonObject(URL)` opens an `HttpURLConnection`, sends a GET request, and checks the HTTP status code.
4. If the response is `200 OK`, the response body is parsed with Gson into a `JsonObject`.
5. The higher-level helper method reads the JSON field it cares about and returns a simplified result to the caller.

### Mermaid relationship diagram

```mermaid
flowchart TD
CurrencyRateAPI["CurrencyRateAPI"] --> ConfigProperties["config.properties"]
CurrencyRateAPI --> ExchangeRateAPI["ExchangeRate API"]
CurrencyRateAPI --> GsonJson["Gson JsonObject"]
CurrencyRateAPI --> Slf4jLogger["SLF4J Logger"]
```

### Implementation details

- `getApiKeyService()` uses the class loader to locate `config.properties` on the runtime classpath.
- If the file is missing, it logs an error and returns `null` rather than throwing.
- `getJsonObject(URL)` only returns a parsed JSON object when the HTTP status is `HTTP_OK`.
- Error handling is intentionally broad: request failures and parsing issues are logged, then the method returns `null`.
- `getCurrencyCode()` assumes the API response contains a `conversion_rates` object and returns its keys as a `String[]`.
- `convert(...)` assumes the API response contains `conversion_result` and returns that value via `toString()`.

## Data Model

There are no local entity or DTO classes in this package. The module works directly with JSON responses from the remote service.

The relevant response shapes inferred from the code are:

- `conversion_rates` — a JSON object whose keys represent supported currency codes
- `conversion_result` — a JSON field containing the converted amount for a currency pair request

## Dependencies and Integration

### External libraries

- **Gson**: used for parsing HTTP responses into `JsonObject` / `JsonElement`
- **SLF4J**: used for logging failures and missing configuration
- **Java standard library**: used for `HttpURLConnection`, `URL`, `URI`, `Properties`, `InputStream`, and `BigDecimal`

### External service

This module integrates with the ExchangeRate API hosted at `https://v6.exchangerate-api.com/v6/`.

### Configuration

`getApiKeyService()` expects a `config.properties` file on the classpath with an `API_KEY` entry. Without it, request construction cannot succeed.

## Notes for Developers

- **Null handling matters.** `getApiKeyService()` and `getJsonObject(...)` can both return `null`. Callers must handle those cases before dereferencing results.
- **The conversion method is brittle.** `convert(...)` immediately calls `.get("conversion_result")` on the returned object, so a failed request or unexpected response will likely trigger a `NullPointerException`.
- **The class is synchronous.** All network access is done directly in the calling thread.
- **The base URL is assembled by string concatenation.** If the API path changes, update `getURL()` and the path construction in the helper methods together.
- **Configuration is read on every key lookup.** There is no caching of `config.properties`, which keeps the implementation simple but means repeated calls re-read the resource.

## Reference

- [CurrencyRateAPI](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:19)