Currency Exchange Service

Overview

The Currency Exchange Service is a Spring Boot application that provides currency conversion functionalities, including retrieving exchange rates, converting amounts between currencies, and querying conversion history. The application uses the CurrencyLayer API for obtaining real-time exchange rates.

Table of Contents

1. Live Demo
2. Installation
   • Prerequisites
   • Building the Docker Image
   • Running the Docker Container
3. Configuration
4. API Endpoints
   • Get Exchange Rate
   • Convert Amount
   • Get Conversion History by Transaction ID
   • Get Conversion History by Date
   • Get Supported Currencies
5. Swagger UI
6. H2 Console
7. API Error Codes
8. License

Live Demo

You can access a live demo of the application at:

• Application URL: http://173.249.13.172:8092
• Swagger UI: http://173.249.13.172:8092/currency/swagger-ui/index.html
• H2 Console: http://173.249.13.172:8092/currency/h2-console

Installation

Prerequisites

Before you begin, ensure you have the following installed on your machine:

• Docker: Install Docker
• Java 21: Make sure Java 21 is installed and set as your default JDK.
• Gradle: Install Gradle if you want to build the project manually without Docker.

Building the Docker Image

To build the Docker image for the Currency Exchange Service, use the following command:

docker build -t currency-exchange .

Running the Docker Container

To run the Docker container with the necessary environment variables:

docker run -d -e API_KEY=your_api_key -p 8092:8092 currency-exchange

• Replace your_api_key with your CurrencyLayer API key.
• The application will be accessible at http://localhost:8092.

Configuration

The application uses environment variables for configuration:

• API_KEY: Your CurrencyLayer API key. If not provided, the service will failed to retrieve exchange rates.
• H2 Database: The application uses an in-memory H2 database for testing and development purposes.

API Endpoints

Get Exchange Rate

Description: Retrieve the exchange rate between two currencies.

• URL: /api/v1/exchange-rate/{baseCurrency}/{targetCurrency}
• Method: GET
• Path Variables:
  • baseCurrency: The currency to convert from (e.g., USD).
  • targetCurrency: The currency to convert to (e.g., EUR).
• Response: 200 OK with exchange rate.

Example Request:

curl http://localhost:8092/currency/api/v1/exchange-rate/USD/EUR

Example Response:

{
"rate": 0.893
}

Convert Amount

Description: Convert a specified amount from one currency to another.

• URL: /api/v1/conversion
• Method: POST
• Request Body:

  {
  "baseCurrency": "USD",
  "targetCurrency": "EUR",
  "amount": 100.0
  }

• Response: 200 OK with conversion result.

Example Request:

curl -X POST http://localhost:8092/currency/api/v1/conversion \\
-H "Content-Type: application/json" \\
-d '{"baseCurrency": "USD", "targetCurrency": "EUR", "amount": 100.0}'

Example Response:

{
"transactionId": "4f6d68e2-b9c5-4f53-8397-d4728b41b2d1",
"conversionAmount": 89.3
}

Get Conversion History by Transaction Id

Description: Retrieve conversion details using a transaction Id.

• URL: /api/v1/conversion-history/{transactionId}
• Method: GET
• Path Variables:
  • transactionId: The ID of the transaction.
• Response: 200 OK with transaction details.

Example Request:

curl http://localhost:8092/currency/api/v1/conversion-history/4f6d68e2-b9c5-4f53-8397-d4728b41b2d1

Example Response:

{
"transactionId": "4f6d68e2-b9c5-4f53-8397-d4728b41b2d1",
"baseCurrency": "USD",
"targetCurrency": "EUR",
"baseAmount": 100.0,
"conversionAmount": 89.3,
"conversionDate": "2024-08-24T14:45:00"
}

Get Conversion History by Date

Description: Retrieve a paginated list of conversions that occurred on a requested date.

• URL: /api/v1/conversion-history
• Method: GET
• Query Parameters:
  • date: The date of the conversions (format: YYYY-MM-DD).
  • page: The page number (default: 0).
  • size: The number of records per page (default: 10).
• Response: 200 OK with a list of conversion history.

Example Request:

curl http://localhost:8092/currency/api/v1/conversion-history?date=2024-08-24&page=0&size=2

Example Response:

{
  "totalPages": 1,
  "totalElements": 2,
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "sorted": false,
      "empty": true,
      "unsorted": true
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "size": 10,
  "content": [
    {
      "transactionId": "4f6d68e2-b9c5-4f53-8397-d4728b41b2d1",
      "baseCurrency": "USD",
      "targetCurrency": "EUR",
      "baseAmount": 100.0,
      "conversionAmount": 89.3,
      "conversionDate": "2024-08-24T21:20:48.456271"
    },
    {
      "transactionId": "4e1d34b6-28b1-40b3-92f4-0a9c4fbb14b8",
      "baseCurrency": "TRY",
      "targetCurrency": "EUR",
      "baseAmount": 10,
      "conversionAmount": 0.26,
      "conversionDate": "2024-08-24T21:21:48.456271"
    }
  ],
  "number": 0,
  "sort": {
    "sorted": false,
    "empty": true,
    "unsorted": true
  },
  "numberOfElements": 2,
  "first": true,
  "last": true,
  "empty": false
}

Get Supported Currencies

Description: Retrieve a list of all supported currencies.

• URL: /api/v1/supported-currencies
• Method: GET
• Response: 200 OK with a list of supported currencies.

Example Request:

curl http://localhost:8092/currency/api/v1/supported-currencies

Example Response:

{
"USD": "United States Dollar",
"EUR": "Euro",
"GBP": "British Pound Sterling"
}

Swagger UI

The application includes Swagger UI for exploring and testing the API endpoints.

• URL: http://localhost:8092/currency/swagger-ui/index.html
• Description: Access the Swagger UI to interact with and explore the available API endpoints.

H2 Console

The application uses an in-memory H2 database for development and testing. To access the H2 console:

• URL: http://localhost:8092/currency/h2-console
• JDBC URL: jdbc:h2:mem:testdb
• Username: sa
• Password: password

API Error Codes

The following error codes may be returned by the API in various error scenarios:

• "bad_request": Invalid request. Please check the input parameters.
• "entity_not_found": The requested entity was not found.
• "internal_server_error": An unexpected error occurred on the server.
• "api_limit_exceeded": The external API rate limit has been exceeded.
• "invalid_api_credentials": The API credentials provided are invalid or the user is inactive.
• "invalid_api_request": The API request was invalid or improperly formatted.
• "external_api_error": An error occurred while fetching data from the external API.
• "external_api_timeout": The request to the external API timed out.

These error codes help in identifying and handling different types of errors that might occur while interacting with the Currency Exchange Service. You can use these codes in your application to provide more informative error messages to users or to implement specific error-handling logic.

License

This project is licensed under the MIT License. See the LICENSE file for details.