Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Docker

Version 20.10 or higher

Docker Compose

Version 2.0 or higher

.NET 8 SDK

Required for local development (optional for Docker)

PostgreSQL Client

psql or any PostgreSQL client for database setup

​
Setup Steps

1

Clone the Repository

Clone the project and navigate to the source directory:
git clone <repository-url>
cd CurrencyExchange
2

Configure Environment Variables

Create a .env file in the project root with your PostgreSQL password:
password=your_secure_password
The default configuration uses alexpg as the username and currencies as the database name. These can be modified in docker-compose.yaml.
3

Start PostgreSQL with Docker Compose

Launch the PostgreSQL container:
docker compose up -d
This will start PostgreSQL on port 5432 with a persistent volume named currencies.
4

Initialize the Database

Connect to PostgreSQL and create the required tables:
psql -h localhost -U alexpg -d currencies
Run the following SQL commands from data.sql:
-- Create tables
CREATE TABLE currencies (
  id SERIAL PRIMARY KEY, 
  code VARCHAR(400), 
  fullname VARCHAR(400), 
  sign VARCHAR(400)
);

CREATE TABLE exchangerates (
  id SERIAL PRIMARY KEY, 
  basecurrencyid INT REFERENCES currencies(id), 
  targetcurrencyid INT REFERENCES currencies(id), 
  rate REAL
);

-- Add unique indexes
CREATE UNIQUE INDEX ix_code ON currencies (code);
CREATE UNIQUE INDEX ix_currencyids ON exchangerates (basecurrencyid, targetcurrencyid);

-- Insert sample data
INSERT INTO currencies (code, fullname, sign) 
VALUES 
  ('USD', 'US Dollar', '$'),
  ('RUB', 'Russian Ruble', '₽');

INSERT INTO exchangerates (basecurrencyid, targetcurrencyid, rate) 
VALUES 
  (1, 2, 82.25),  -- USD to RUB
  (2, 1, 0.012);  -- RUB to USD
5

Build and Run the API

Build the Docker image and run the application:
docker build -t currencyexchangeback .
docker run -d -p 8080:8080 --name currencies-backend currencyexchangeback
Alternatively, run locally with .NET:
cd CurrencyExchange
dotnet restore
dotnet run
The API will be available at http://localhost:8080
6

Verify Installation

Open Swagger UI in your browser:
http://localhost:8080/swagger
You should see the interactive API documentation.

​
Your First API Call

Let’s perform a currency conversion from USD to RUB: 
curl -X GET "http://localhost:8080/api/Exchange/from=USD&to=RUB&amount=100" \
  -H "accept: application/json"

​
Expected Response

{
  "baseCurrency": {
    "id": 1,
    "code": "USD",
    "fullName": "US Dollar",
    "sign": "$"
  },
  "targetCurrency": {
    "id": 2,
    "code": "RUB",
    "fullName": "Russian Ruble",
    "sign": "₽"
  },
  "rate": 82.25,
  "amount": 100,
  "recalculateAmount": 8225.00
}
The conversion endpoint is defined in ExchangeController.cs:16. It intelligently handles direct rates, reverse rates, and cross-rates automatically.

​
Additional API Endpoints

Try these other endpoints to explore the API:

​
Get All Currencies

curl -X GET "http://localhost:8080/api/Currency" \
  -H "accept: application/json"

​
Search Currencies

curl -X GET "http://localhost:8080/api/Currency/Dollar" \
  -H "accept: application/json"

​
Get All Exchange Rates

curl -X GET "http://localhost:8080/api/ExchangeRate" \
  -H "accept: application/json"

​
Add a New Currency

curl -X POST "http://localhost:8080/api/Currency" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 0,
    "code": "EUR",
    "fullName": "Euro",
    "sign": "€"
  }'

​
Add an Exchange Rate

curl -X POST "http://localhost:8080/api/ExchangeRate" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "baseCurrencyCode": "EUR",
    "targetCurrencyCode": "USD",
    "rate": 1.08
  }'

​
Configuration

​
Automatic Rate Updates

The API automatically updates exchange rates from the Central Bank of Russia. Configure the update frequency in appsettings.json:
appsettings.json
{
  "CurrencyReceiptPeriod": {
    "Period": "300"  // Update every 300 seconds (5 minutes)
  }
}
The background service is configured in Program.cs:29-33 using the CBRExchangeRate hosted service.

​
CORS Configuration

If you’re building a frontend application, configure allowed origins in appsettings.json:
appsettings.json
{
  "CorsConfig": {
    "Origin": [
      "http://localhost:4200",
      "https://your-frontend-domain.com"
    ]
  }
}

​
Database Connection

Modify the connection string in appsettings.json if needed:
appsettings.json
{
  "ConnectionStrings": {
    "CurrencyExchangeDBContext": "Host=localhost;Database=currencies;Port=5432;User ID=alexpg;Password=your_password;CommandTimeout=1200;"
  }
}
For Docker deployment, use Host=postgres instead of Host=localhost to connect to the PostgreSQL container.

​
Troubleshooting

​
Database Connection Errors

If you see connection errors, ensure:
  • PostgreSQL container is running: docker ps
  • Connection string matches your configuration
  • Database and tables are created

​
Rate Updates Not Working

The automatic rate update service (CBRExchangeRate.cs:13) requires:
  • Currency pairs with format [CURRENCY_CODE] → RUB in the database
  • Network access to the Central Bank of Russia SOAP service
  • Valid currency codes matching CBR’s currency list

​
Validation Errors

The API validates:
  • Currency codes: 3-5 uppercase letters (validated in Currency.cs:25)
  • Currency names: 3-60 characters, letters and spaces only
  • Exchange rates: Must be between 0 and 99,999,999 (validated in ExchangeRate.cs:28-31)

​
Next Steps

Architecture

Understand the clean architecture design and layer responsibilities

API Reference

Explore all available endpoints and their parameters

Build docs developers (and LLMs) love

Get started for freeTalk to us