Currency Exchange

Convert amounts between currencies using current exchange rates

Convert Currency

GET /api/Exchange/from={baseCurrencyCode}&to={targetCurrencyCode}&amount={amount}

curl "http://localhost:8080/api/Exchange/from=USD&to=EUR&amount=100"

Converts an amount from one currency to another using the current exchange rate.

Path Parameters

baseCurrencyCode · string · required

Currency code to convert from (e.g., “USD”)

targetCurrencyCode · string · required

Currency code to convert to (e.g., “EUR”)

amount · float · required

Amount to convert (must be a positive number)

Exchange Rate Resolution

The API uses an intelligent exchange rate resolution system with three strategies:

1. Direct Rate: First attempts to find a direct exchange rate from base to target currency
2. Reverse Rate: If no direct rate exists, calculates using the reverse rate (1 / rate) from target to base
3. Cross Rate: If neither direct nor reverse rate exists, calculates using cross rates through intermediate currencies (e.g., USD→RUB→EUR)

Response

exchange · object

Currency conversion result

baseCurrency · object

Source currency information

id · integer

Currency ID

code · string

Currency code

fullName · string

Full currency name

sign · string

Currency symbol

targetCurrency · object

Target currency information (same structure as baseCurrency)

rate · float

Exchange rate used for conversion

amount · float

Original amount in base currency

convertedAmount · float

Converted amount in target currency

Example Response

{
  "baseCurrency": {
    "id": 1,
    "code": "USD",
    "fullName": "United States Dollar",
    "sign": "$"
  },
  "targetCurrency": {
    "id": 2,
    "code": "EUR",
    "fullName": "Euro",
    "sign": "€"
  },
  "rate": 0.92,
  "amount": 100.0,
  "convertedAmount": 92.0
}

Example Usage

Convert USD to EUR:

curl "http://localhost:8080/api/Exchange/from=USD&to=EUR&amount=100"

Convert EUR to GBP:

curl "http://localhost:8080/api/Exchange/from=EUR&to=GBP&amount=50"

Convert with decimal amount:

curl "http://localhost:8080/api/Exchange/from=USD&to=JPY&amount=99.99"

Conversion Logic

The conversion follows this formula:

convertedAmount = amount × rate

For example:

• Converting 100 USD to EUR with rate 0.92:
  • 100 × 0.92 = 92.0 EUR

Error Responses

Currency not found:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "message": ["Не удалось найти валюту"]
  }
}

No exchange rate available:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "An error occurred while processing the request.",
  "status": 500,
  "errors": {
    "message": ["Не удалось найти или создать подходящий обменный курс"]
  }
}

Invalid amount format:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "amount": ["The value 'invalid' is not valid for amount."]
  }
}

Multi-Currency Conversion Examples

Simple Direct Conversion

When a direct exchange rate exists between two currencies:

curl "http://localhost:8080/api/Exchange/from=USD&to=EUR&amount=250"

Response:

{
  "baseCurrency": {
    "id": 1,
    "code": "USD",
    "fullName": "United States Dollar",
    "sign": "$"
  },
  "targetCurrency": {
    "id": 2,
    "code": "EUR",
    "fullName": "Euro",
    "sign": "€"
  },
  "rate": 0.92,
  "amount": 250.0,
  "convertedAmount": 230.0
}

Reverse Rate Conversion

When only the reverse rate exists (e.g., EUR→USD exists, but you need USD→EUR):

curl "http://localhost:8080/api/Exchange/from=EUR&to=USD&amount=100"

The system automatically calculates the reverse rate.

Cross Rate Conversion

When no direct or reverse rate exists, the system uses intermediate currencies:

curl "http://localhost:8080/api/Exchange/from=GBP&to=JPY&amount=50"

The system might convert GBP→USD→JPY automatically.

Notes

• All amounts are returned as floating-point numbers
• Exchange rates may be automatically created and saved when using reverse or cross rate strategies
• The API ensures currency codes exist before performing conversions
• Validation errors include descriptive messages (some in Russian)