BCV API

REST API in Go for fetching exchange rates from Banco Central de Venezuela (BCV) for USD and EUR.

About This Project

This API was born out of necessity. The Banco Central de Venezuela (BCV) does not provide an official public API for accessing exchange rates, which created a challenge for my SaaS application. To solve this problem, I developed this custom API that scrapes the BCV website to provide reliable and up-to-date exchange rate data.

The project is built with Go (Golang), chosen for its exceptional performance and efficiency. As I continue to explore and learn this powerful language, this project represents one of my initial steps into the Go ecosystem. It's a testament to my growing knowledge and understanding of Go's concurrency model, HTTP handling, and web scraping capabilities.

✨ Features

• 🧹 Clean and optimized code
• 🏗️ Modular and scalable architecture
• 🛡️ Robust error handling
• ⚡ Concurrent rate fetching for improved performance
• 🎯 Intelligent scraping with multiple extraction strategies
• ⚙️ Environment variable configuration
• 🔒 SSL certificate handling for BCV website
• 🚦 Rate limiting (60 requests per minute per IP)
• 💾 In-memory caching with TTL to reduce BCV website requests

📋 Requirements

• Go 1.21 or higher
• Internet connection

🚀 Installation

1. Clone or download the project

2. Install dependencies:

make deps
# Or manually:
go mod download
go mod tidy

3. Build the project:

make build
# Or manually:
go build -o bin/bcv-api ./cmd/server

🏃 Running

Development mode

make run
# Or manually:
go run ./cmd/server/main.go

Production mode

./bin/bcv-api

Custom port

PORT=3000 make run
# Or
PORT=3000 ./bin/bcv-api

Custom configuration

# Set cache TTL to 10 minutes and rate limit to 100 requests/minute
CACHE_TTL=10m RATE_LIMIT_PER_MIN=100 ./bin/bcv-api

# Custom port, cache, and timeout
PORT=3000 CACHE_TTL=5m HTTP_TIMEOUT=45s ./bin/bcv-api

📡 Endpoints

Get USD rate

GET http://localhost:8080/api/rates/dollar

Response:

{
  "success": true,
  "data": {
    "currency": "Dollar",
    "rate": "36.50",
    "date": "2024-01-15T10:30:00Z"
  }
}

Get EUR rate

GET http://localhost:8080/api/rates/euro

Response:

{
  "success": true,
  "data": {
    "currency": "Euro",
    "rate": "40.25",
    "date": "2024-01-15T10:30:00Z"
  }
}

Get all rates

GET http://localhost:8080/api/rates/all

Response:

{
  "success": true,
  "data": {
    "dollar": {
      "currency": "Dollar",
      "rate": "36.50",
      "date": "2024-01-15T10:30:00Z"
    },
    "euro": {
      "currency": "Euro",
      "rate": "40.25",
      "date": "2024-01-15T10:30:00Z"
    }
  }
}

📁 Project Structure

bcv-api/
├── cmd/
│   └── server/
│       └── main.go          # Application entry point
├── internal/
│   ├── cache/               # In-memory caching
│   │   └── cache.go
│   ├── config/              # Configuration management
│   │   └── config.go
│   ├── handler/             # HTTP handlers
│   │   ├── home_handler.go
│   │   └── tasa_handler.go
│   ├── middleware/          # HTTP middleware
│   │   └── ratelimit.go
│   ├── models/              # Data models
│   │   └── tasa.go
│   └── service/             # Business logic
│       └── bcv_service.go
├── go.mod                   # Dependencies
├── go.sum                   # Dependency checksums
├── Makefile                 # Useful commands
├── LICENSE                  # MIT License
└── README.md

🛠️ Make Commands

• make build - Build the project
• make run - Run server in development mode
• make clean - Clean compiled files
• make test - Run tests
• make deps - Download and update dependencies
• make install - Install dependencies and build

🔧 Technologies

• Go 1.21+: Programming language chosen for its speed and efficiency
• Gorilla Mux: HTTP router for flexible routing
• GoQuery: HTML parser (similar to jQuery) for web scraping
• golang.org/x/time: Rate limiting library
• net/http: Native Go HTTP client

💡 Technical Details

Why Go?

Go was selected for this project because:

• ⚡ Performance: Go's compiled nature and efficient runtime make it ideal for high-performance APIs
• 🔄 Concurrency: Built-in goroutines allow for concurrent rate fetching, improving response times
• 🎯 Simplicity: Clean syntax and strong standard library reduce complexity
• 📚 Learning: This project serves as a learning experience in Go's ecosystem

Architecture

The project follows clean architecture principles:

• 🔀 Separation of concerns: Handlers, services, and models are clearly separated
• 💉 Dependency injection: Services are injected into handlers
• 🛡️ Error handling: Comprehensive error handling throughout the codebase
• ⚡ Concurrent processing: Rates are fetched concurrently for optimal performance

💾 Caching

The API implements an in-memory cache to improve performance and reduce load on the BCV website:

• Automatic caching: Exchange rates are cached automatically after the first request
• Configurable TTL: Cache duration is configurable via CACHE_TTL environment variable (default: 5 minutes)
• Per-currency cache: Dollar and Euro rates are cached separately
• Thread-safe: Safe for concurrent requests
• Automatic cleanup: Expired cache entries are automatically removed

Benefits:

• ⚡ Faster response times for cached requests
• 🔄 Reduced load on BCV website
• 💰 Lower bandwidth usage
• 🎯 Better user experience

Example:

# First request: Fetches from BCV website (~500ms)
GET /api/rates/dollar

# Subsequent requests within cache TTL: Returns from cache (~1ms)
GET /api/rates/dollar  # Cached response

📝 Notes

• The API fetches rates by scraping the official BCV website (https://www.bcv.org.ve/)
• HTML selectors may need updates if BCV changes their website structure
• The service fetches rates concurrently for better performance
• SSL certificate handling is automatic
• Cached rates are served instantly without making requests to BCV

🐛 Troubleshooting

SSL certificate error

The code automatically handles BCV SSL certificate issues.

Rates not found

If BCV changes their website structure, you may need to update selectors in internal/service/bcv_service.go.

⚙️ Configuration

The API can be configured using environment variables. All settings are optional and have sensible defaults.

Environment Variables

Variable	Default	Description	Example
PORT	8080	Server port	PORT=3000
BCV_URL	https://www.bcv.org.ve	BCV website URL	BCV_URL=https://www.bcv.org.ve
HTTP_TIMEOUT	30s	HTTP request timeout	HTTP_TIMEOUT=45s or HTTP_TIMEOUT=1m
CACHE_TTL	5m	Cache TTL for exchange rates	CACHE_TTL=10m or CACHE_TTL=1h
USER_AGENT	(default browser)	User agent for HTTP requests	USER_AGENT=MyApp/1.0
RATE_LIMIT_PER_MIN	60	Rate limit per IP (requests per minute)	RATE_LIMIT_PER_MIN=100

Configuration Examples

Basic usage with defaults:

./bin/bcv-api

Custom port:

PORT=3000 ./bin/bcv-api

Extended cache (10 minutes):

CACHE_TTL=10m ./bin/bcv-api

Higher rate limit:

RATE_LIMIT_PER_MIN=100 ./bin/bcv-api

Full custom configuration:

PORT=3000 \
CACHE_TTL=10m \
HTTP_TIMEOUT=45s \
RATE_LIMIT_PER_MIN=100 \
./bin/bcv-api

Cache Behavior

The API uses in-memory caching to reduce requests to the BCV website:

• Cache TTL: Configurable via CACHE_TTL (default: 5 minutes)
• Automatic cleanup: Expired entries are automatically removed
• Per-currency caching: Dollar and Euro rates are cached separately
• Thread-safe: Safe for concurrent access

When a cached rate is requested, the API returns the cached value immediately without making a request to BCV, significantly improving response times.

🚧 Future Improvements

This project is actively being developed and improved. The following features are planned for future releases:

• 🧪 Unit Tests: Comprehensive test coverage for services, handlers, and utilities
• 🐛 Advanced Debugging: Enhanced logging and debugging capabilities with structured logging
• 🛡️ Advanced Error Handling: More specific error types and better error messages for easier troubleshooting
• ❤️ Health Check: Add /health endpoint for monitoring and load balancer integration
• 📚 API Documentation: Generate OpenAPI/Swagger documentation for better developer experience

Note: Rate limiting, caching, and environment variable configuration have been implemented and are now active.

Contributions are welcome! If you'd like to contribute or suggest new features, feel free to open an issue or submit a pull request.

👨‍💻 Developer

Sebastian Cheikh

This project represents my journey into Go programming. As I continue to learn and grow with this beautiful language, I'm building practical solutions that solve real-world problems.

🤝 Contributing

Contributors are welcome! This project is open to contributions. Whether you want to:

• 🐛 Report bugs
• 💡 Suggest new features
• 🔧 Submit pull requests
• 📖 Improve documentation
• ⭐ Share feedback

Your contributions help make this project better for everyone. Feel free to open an issue or submit a pull request.

📄 License

MIT License