# Com / Github / Blaxk3 / Api

## Overview

The `com.github.blaxk3.api` package contains a small API wrapper for working with exchange-rate data from the ExchangeRate-API service. In practice, it appears to provide three core capabilities: loading the API key from local configuration, building request URLs, and fetching/parsing JSON responses for currency metadata and conversions.

This package is intentionally lightweight: it centers on a single class, `CurrencyRateAPI`, which hides HTTP and JSON handling behind a few convenience methods. That makes it the integration point for any part of the application that needs to list supported currencies or convert an amount between two currency codes.

## Key Classes and Interfaces

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

`CurrencyRateAPI` is the sole public class in this package and serves as the service boundary for exchange-rate lookups. It encapsulates configuration loading, URL construction, HTTP requests, and JSON parsing so callers do not need to deal with those details directly.

The class depends on standard JDK networking classes, SLF4J logging, and Gson for JSON parsing. It does not expose any state of its own; each method performs a one-off operation and returns either a value or `null` when something goes wrong.

#### Responsibilities

- Load the ExchangeRate-API key from `config.properties`
- Build the base API URL for requests
- Execute GET requests and parse JSON responses
- Extract available currency codes from the latest-rates endpoint
- Request a conversion result for a currency pair and amount

#### Important methods

- [`getApiKeyService()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:23) loads `config.properties` from the classpath and returns the `API_KEY` property.
- [`getURL()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:38) constructs the API base URL using the configured key.
- [`getJsonObject(URL url)`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:42) performs an HTTP GET request and parses the response body into a `JsonObject`.
- [`getCurrencyCode()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:61) fetches the USD latest-rates payload and returns the supported currency codes found under `conversion_rates`.
- [`convert(String foreignCurrency1, String foreignCurrency2, BigDecimal amount)`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:72) requests a pair conversion and returns the `conversion_result` field as a string.

## How It Works

### Request flow

The class follows a simple linear flow for every API operation:

1. Read the API key from `config.properties`
2. Build the base URL for the ExchangeRate-API endpoint
3. Append the specific resource path needed for the operation
4. Open an `HttpURLConnection`
5. On HTTP 200, parse the response body with Gson
6. Extract the field the caller needs

### Supported operations

#### Loading configuration

[`getApiKeyService()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:23) loads `config.properties` from the application classpath using the class loader. If the file is missing or cannot be read, the method logs an error and returns `null`.

This method is the foundation for the rest of the class: every URL ultimately depends on the API key returned here.

#### Building the base URL

[`getURL()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:38) concatenates the ExchangeRate-API root path with the configured API key. The resulting string is used as the base for the more specific endpoints in the other methods.

#### Fetching and parsing JSON

[`getJsonObject(URL url)`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:42) is the shared HTTP helper. It:

- opens an `HttpURLConnection`
- sets the request method to `GET`
- checks the response code
- if the response is `HTTP_OK`, parses the response body into a `JsonObject`
- logs failures and returns `null` if anything goes wrong

Because this method returns `null` on failure, callers must be careful to check for a missing response before dereferencing the result.

#### Listing currency codes

[`getCurrencyCode()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:61) builds a request for the `latest/USD` endpoint, then looks for the `conversion_rates` object in the response. If present, it returns the object’s keys as a `String[]`.

This method appears to be used as a simple way to discover supported currency identifiers from the external service.

#### Converting an amount

[`convert(String foreignCurrency1, String foreignCurrency2, BigDecimal amount)`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:72) builds a `/pair/.../.../...` URL, sends the request, and returns the `conversion_result` field from the JSON response.

The method accepts:

- `foreignCurrency1` - source currency code
- `foreignCurrency2` - target currency code
- `amount` - amount to convert

It returns the conversion result as a `String`, not as a numeric type. That means callers may need to parse or format the value themselves depending on how they want to display or use it.

## Data Model

This package does not define its own domain model classes or DTOs. Instead, it works directly with JSON payloads from the external API using Gson.

The important data structures are:

- `JsonObject` for the parsed response body
- `conversion_rates` object for currency-code discovery
- `conversion_result` field for pair conversion results

Because there is no internal model layer, the package is tightly coupled to the response shape returned by the ExchangeRate-API service.

## Dependencies and Integration

### External libraries

- **Gson** - used to parse the HTTP response body into `JsonObject` and `JsonElement`
- **SLF4J** - used for error logging
- **JDK networking APIs** - `URL`, `HttpURLConnection`, `URISyntaxException`, `MalformedURLException`
- **JDK configuration APIs** - `Properties`, `InputStream`, `InputStreamReader`
- **BigDecimal** - used for the conversion amount input

### External service integration

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

The code expects:

- a `config.properties` file on the classpath
- an `API_KEY` property inside that file
- response payloads that contain `conversion_rates` and `conversion_result` in the expected places

## Mermaid Diagram

```mermaid
flowchart TD
Module["com.github.blaxk3.api"] --> CurrencyRateAPI["CurrencyRateAPI"]
CurrencyRateAPI --> ConfigFile["config.properties"]
CurrencyRateAPI --> ApiKey["getApiKeyService()"]
CurrencyRateAPI --> BaseUrl["getURL()"]
CurrencyRateAPI --> HttpGet["getJsonObject(URL url)"]
CurrencyRateAPI --> Codes["getCurrencyCode()"]
CurrencyRateAPI --> Convert["convert(String, String, BigDecimal)"]
HttpGet --> ExchangeRateApi["ExchangeRate-API"]
Codes --> ExchangeRateApi
Convert --> ExchangeRateApi
```

## Notes for Developers

- `getApiKeyService()` returns `null` when configuration is missing or unreadable. Any caller that uses `getURL()` or the request methods should assume configuration can fail.
- `getJsonObject(URL url)` also returns `null` on any non-OK response or exception. There is no retry logic or typed error handling in this class.
- `convert(...)` dereferences the returned JSON object immediately. If the request fails, this will likely lead to a `NullPointerException` at runtime.
- The class currently hardcodes the USD latest-rates request inside `getCurrencyCode()`. If another base currency is needed later, that logic would need to be expanded.
- The return type of `convert(...)` is a string representation of the JSON field, so consumers should not assume it is already formatted for display.

## Source References

- [`CurrencyRateAPI`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:19)
- [`CurrencyRateAPI.getApiKeyService()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:23)
- [`CurrencyRateAPI.getURL()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:38)
- [`CurrencyRateAPI.getJsonObject(URL url)`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:42)
- [`CurrencyRateAPI.getCurrencyCode()`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:61)
- [`CurrencyRateAPI.convert(String foreignCurrency1, String foreignCurrency2, BigDecimal amount)`](src/main/java/com/github/blaxk3/api/CurrencyRateAPI.java:72)